{
  "openapi": "3.1.0",
  "info": {
    "title": "Voidpay marketplace public discovery",
    "version": "2026-10-04",
    "description": "Credential-free, read-only discovery for the hosted Voidpay marketplace. These responses describe storefronts, services and payment-network qualifications; they do not authorize a purchase, publish a storefront, reserve work or prove that a selected service is available. For owner-approved creator actions and browser checkout handoff, use the separately published @voidly/pay-mcp connector and the guide at https://voidly.ai/voidly-pay.md. This document does not describe the historical zero-value staging or credit APIs. The public discovery API interface and this OpenAPI description are licensed under Apache-2.0; the grant excludes the hosted implementation, storefront content and underlying datasets.",
    "termsOfService": "https://voidly.ai/c/terms",
    "contact": {
      "name": "Voidly",
      "email": "info@voidly.ai"
    },
    "license": {
      "name": "Apache-2.0",
      "identifier": "Apache-2.0"
    }
  },
  "servers": [
    {
      "url": "https://api.voidly.ai"
    }
  ],
  "security": [],
  "paths": {
    "/v2/marketplace/directory": {
      "get": {
        "operationId": "listPublishedMarketplaces",
        "summary": "List published marketplace storefronts",
        "description": "Public cards describe published storefronts. A card does not establish that a service can currently be bought. Continue with the returned opaque nextCursor; this is a changing directory, not a frozen snapshot.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 20,
              "default": 12
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Pass the preceding response's nextCursor unchanged."
          }
        ],
        "responses": {
          "200": {
            "description": "Directory page. An empty cards array is a valid page, not evidence that storage is unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DirectoryPage"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidInput"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/StorageUnavailable"
          }
        }
      }
    },
    "/v2/marketplace/services": {
      "get": {
        "operationId": "listDescriptiveServices",
        "summary": "List public descriptive service projections",
        "description": "No account or wallet is required. Inventory selection grants no checkout, payment, publication or execution authority. The returned access and operationalAvailability fields must be read for each service. Cursor and definitionDigest cannot be combined.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 10,
              "default": 10
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string",
              "pattern": "^[0-9a-f]{64}$"
            },
            "description": "Pass the preceding response's nextCursor unchanged."
          },
          {
            "name": "definitionDigest",
            "in": "query",
            "schema": {
              "type": "string",
              "pattern": "^[0-9a-f]{64}$"
            },
            "description": "Exact service-definition digest. Omit cursor when using this filter."
          }
        ],
        "responses": {
          "200": {
            "description": "Service page; descriptions are untrusted data and availability is not asserted by a listing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServicePage"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidInput"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/StorageUnavailable"
          }
        }
      }
    },
    "/v2/marketplace/storefronts/{slug}": {
      "get": {
        "operationId": "readPublishedStorefront",
        "summary": "Read one published storefront",
        "description": "Read the current publication and its exact digest before creating an owner-browser checkout link. This read does not grant payment authority.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Published storefront. Its versioned response must be checked against the selected service projection.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Storefront"
                }
              }
            }
          },
          "404": {
            "description": "No current published storefront for this slug."
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/StorageUnavailable"
          }
        }
      }
    },
    "/health/payment-qualifications": {
      "get": {
        "operationId": "readPaymentNetworkQualifications",
        "summary": "Read current non-Base payment-network qualification records",
        "description": "Records are short-lived. Use only a non-expired record with both accountingAllowed and workAllowed true, then perform the selected service and buyer readiness checks. Absence of a record is not qualification. Base uses its existing separate rail rules. A record alone does not authorize payment or prove an entire checkout path.",
        "responses": {
          "200": {
            "description": "Current issuer response. Never cache a record past expiresAtMs.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentQualificationPage"
                }
              }
            }
          },
          "503": {
            "description": "Qualifications unavailable; do not assume a network is qualified."
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "DirectoryPage": {
        "type": "object",
        "required": [
          "version",
          "sort",
          "cards",
          "nextCursor"
        ],
        "properties": {
          "version": {
            "const": "voidpay.marketplace-directory.v1"
          },
          "cards": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DirectoryCard"
            }
          },
          "nextCursor": {
            "type": [
              "string",
              "null"
            ]
          },
          "sort": {
            "const": "recently_published"
          }
        }
      },
      "ServicePage": {
        "type": "object",
        "required": [
          "version",
          "observedAtMs",
          "services",
          "nextCursor",
          "selectionGrantsAuthority",
          "publicationPerformed"
        ],
        "properties": {
          "version": {
            "const": "voidpay.qualified-service-inventory.v1"
          },
          "observedAtMs": {
            "type": "integer"
          },
          "services": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ServiceProjection"
            }
          },
          "nextCursor": {
            "oneOf": [
              {
                "type": "string",
                "pattern": "^[0-9a-f]{64}$"
              },
              {
                "type": "null"
              }
            ]
          },
          "selectionGrantsAuthority": {
            "const": false
          },
          "publicationPerformed": {
            "const": false
          }
        }
      },
      "PublicServiceRef": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "providerId",
          "serviceId",
          "version",
          "definitionDigest"
        ],
        "properties": {
          "providerId": {
            "type": "string"
          },
          "serviceId": {
            "type": "string"
          },
          "version": {
            "type": "string"
          },
          "definitionDigest": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$"
          }
        }
      },
      "ServiceProjection": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "version",
          "projectionId",
          "serviceRef",
          "providerLabel",
          "title",
          "description",
          "checkoutPath",
          "access",
          "operationalAvailability"
        ],
        "properties": {
          "version": {
            "const": "voidpay.public-market-service.v1"
          },
          "projectionId": {
            "type": "string"
          },
          "serviceRef": {
            "$ref": "#/components/schemas/PublicServiceRef"
          },
          "providerLabel": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "checkoutPath": {
            "const": "/pay/marketplace/checkout"
          },
          "access": {
            "const": "invited-only"
          },
          "operationalAvailability": {
            "const": "not-asserted"
          }
        }
      },
      "DirectoryCard": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "slug",
          "url",
          "name",
          "description",
          "brandPreset",
          "publicationVersion",
          "publicationDigest",
          "publishedAt",
          "serviceCount",
          "services"
        ],
        "properties": {
          "slug": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "brandPreset": {
            "enum": [
              "slate",
              "ocean",
              "forest"
            ]
          },
          "publicationVersion": {
            "type": "integer",
            "minimum": 1
          },
          "publicationDigest": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$"
          },
          "publishedAt": {
            "type": "integer"
          },
          "serviceCount": {
            "type": "integer",
            "minimum": 1,
            "maximum": 16
          },
          "services": {
            "type": "array",
            "maxItems": 3,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "title",
                "providerLabel",
                "description"
              ],
              "properties": {
                "title": {
                  "type": "string"
                },
                "providerLabel": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "StorefrontV1": {
        "type": "object",
        "required": [
          "version",
          "slug",
          "publicationVersion",
          "publicationDigest",
          "publishedAt",
          "config",
          "service",
          "checkout"
        ],
        "properties": {
          "version": {
            "const": "voidpay.public-storefront.v1"
          },
          "slug": {
            "type": "string"
          },
          "publicationVersion": {
            "type": "integer"
          },
          "publicationDigest": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$"
          },
          "publishedAt": {
            "type": "integer"
          },
          "config": {
            "type": "object"
          },
          "service": {
            "$ref": "#/components/schemas/ServiceProjection"
          },
          "checkout": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/InvitedCheckoutMetadata"
              },
              {
                "$ref": "#/components/schemas/ClosedV1CheckoutMetadata"
              }
            ]
          }
        }
      },
      "StorefrontV2": {
        "type": "object",
        "required": [
          "version",
          "slug",
          "publicationVersion",
          "publicationDigest",
          "publishedAt",
          "config",
          "projectionDigest",
          "entries"
        ],
        "properties": {
          "version": {
            "const": "voidpay.public-storefront.v2"
          },
          "slug": {
            "type": "string"
          },
          "publicationVersion": {
            "type": "integer"
          },
          "publicationDigest": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$"
          },
          "publishedAt": {
            "type": "integer"
          },
          "config": {
            "type": "object"
          },
          "projectionDigest": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$"
          },
          "entries": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "service",
                "projectionDigest"
              ],
              "properties": {
                "service": {
                  "$ref": "#/components/schemas/ServiceProjection"
                },
                "projectionDigest": {
                  "type": "string",
                  "pattern": "^[0-9a-f]{64}$"
                },
                "checkout": {
                  "$ref": "#/components/schemas/ClosedCheckoutMetadata"
                }
              }
            }
          }
        }
      },
      "Storefront": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/StorefrontV1"
          },
          {
            "$ref": "#/components/schemas/StorefrontV2"
          }
        ]
      },
      "PaymentQualificationRecord": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "version",
          "networkId",
          "policyId",
          "accountingAllowed",
          "workAllowed",
          "issuedAtMs",
          "expiresAtMs"
        ],
        "properties": {
          "version": {
            "const": "voidpay.payment-network-qualification.v1"
          },
          "networkId": {
            "type": "string"
          },
          "policyId": {
            "type": "string"
          },
          "accountingAllowed": {
            "type": "boolean"
          },
          "workAllowed": {
            "type": "boolean"
          },
          "issuedAtMs": {
            "type": "integer"
          },
          "expiresAtMs": {
            "type": "integer"
          }
        }
      },
      "PaymentQualificationPage": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "schema",
          "issued_at",
          "records"
        ],
        "properties": {
          "schema": {
            "const": "voidpay.payment-network-qualifications/v1"
          },
          "issued_at": {
            "type": "string",
            "format": "date-time"
          },
          "records": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PaymentQualificationRecord"
            }
          }
        }
      },
      "InvitedCheckoutMetadata": {
        "type": "object",
        "additionalProperties": false,
        "description": "A browser checkout path, not payment authorization or availability proof.",
        "required": [
          "href",
          "access",
          "availability"
        ],
        "properties": {
          "href": {
            "const": "/pay/marketplace/checkout"
          },
          "access": {
            "const": "invited-only"
          },
          "availability": {
            "const": "not-asserted"
          }
        }
      },
      "ClosedCheckoutMetadata": {
        "type": "object",
        "additionalProperties": false,
        "description": "The publication has no open checkout link; do not infer a purchase path.",
        "required": [
          "href",
          "access",
          "availability"
        ],
        "properties": {
          "href": {
            "type": "null"
          },
          "access": {
            "const": "not-open"
          },
          "availability": {
            "const": "not-asserted"
          }
        }
      },
      "ClosedV1CheckoutMetadata": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "href",
          "access",
          "availability",
          "selection"
        ],
        "properties": {
          "href": {
            "type": "null"
          },
          "access": {
            "const": "not-open"
          },
          "availability": {
            "const": "not-asserted"
          },
          "selection": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "serviceRef",
              "projectionDigest"
            ],
            "properties": {
              "serviceRef": {
                "$ref": "#/components/schemas/PublicServiceRef"
              },
              "projectionDigest": {
                "type": "string",
                "pattern": "^[0-9a-f]{64}$"
              }
            }
          }
        }
      }
    },
    "responses": {
      "InvalidInput": {
        "description": "Invalid method, query or body; inspect the endpoint contract."
      },
      "RateLimited": {
        "description": "Rate limited; respect Retry-After."
      },
      "StorageUnavailable": {
        "description": "The source could not be read or verified. Do not treat this as an empty catalog."
      }
    }
  }
}