> ## Documentation Index > Fetch the complete documentation index at: https://docs.faremeter.xyz/llms.txt > Use this file to discover all available pages before exploring further. # Publishing on a Marketplace > How a publisher puts an x402-paid API behind a marketplace proxy. A publisher is anyone who has an API they want to charge for. On a marketplace, the publisher hands the operator an OpenAPI spec describing their endpoints and pricing; the operator's API nodes do the rest. This page describes the publisher's side of the OSS marketplace stack. If you want to run your own server with payment middleware instead of routing through a marketplace, see [Server middleware](/server/middleware-overview) — that path does not require any of the components below. ## What you provide A marketplace tenant is configured by three things: 1. **A backend URL.** The address of your existing API. The proxy forwards paid requests here. 2. **An OpenAPI spec with `x-faremeter-pricing` extensions.** This declares the pricing rules and any response fields the proxy should capture for usage-based billing. 3. **A wallet to receive funds.** Settlement deposits into this address. You do not write Lua, nginx config, or settlement code. The marketplace operator runs everything; you submit the spec and wait for traffic. ## The OpenAPI spec The gateway SDK reads `x-faremeter-pricing` extensions from your spec to generate the proxy config. The extension lives at the operation level (and can also be declared at the path or document level) with `rules` describing what to charge for and, for usage-based pricing, `rates` mapping captured fields to per-unit prices. A minimal example with a fixed-price endpoint and a usage-priced endpoint: ```yaml theme={null} openapi: 3.1.0 info: title: Example API version: 1.0.0 servers: - url: https://api.example.com paths: /v1/quote: get: summary: Get a price quote x-faremeter-pricing: rules: - match: "true" rates: flat: 10000 # micro-USDC; $0.01 per call responses: "200": description: A quote /v1/chat: post: summary: Chat completion x-faremeter-pricing: rules: - match: "true" capture: "$.response.body.usage.total_tokens" rates: tokens: 100 # micro-USDC per token responses: "200": description: Chat response ``` The capture expression is JSONPath against the upstream response. The gateway parses only the chunks that could contain the captured field, so adding capture-based pricing does not impose a per-byte parse cost on every request. For the full extension surface, transports (HTTP JSON, SSE, WebSocket), and edge cases, see the [Gateway SDK page](/marketplace/gateway) and the [`@faremeter/gateway-nginx` README](https://github.com/faremeter/faremeter/tree/main/packages/gateway-nginx). ## Restricting payment with `x-faremeter-policy` `x-faremeter-pricing` decides what a route costs. `x-faremeter-policy` decides *how* it may be paid: which payment schemes may serve the route, and whether a given scheme is forced to one-phase or two-phase capture. It is a separate extension because the concerns are separate — you can price a route without constraining it, but when you do want to constrain it, the constraint lives next to the price. Why this matters: the x402 `exact` scheme has no escrow. In two-phase mode (authorize now, capture later) the payer can move the authorized funds before capture lands, so the operator carries a rug-pull window. On a low-value route that window is a fine trade for the deferred-capture flow; on a high-value route it is not. A policy lets the operator close it per route — either by pinning `exact` to one-phase (capture happens immediately, so there is no window) or by disallowing it entirely in favor of a scheme that escrows. See [Payment Schemes](/concepts/payment-schemes) for one-phase versus two-phase capture and what each scheme guarantees. The extension carries two optional fields: * **`allow`** — the set of schemes and methods that may serve this route, each written as `":"` (for example `"x402:exact"` or `"mpp:solana"`). The protocol prefix is case-sensitive and lowercase. * Omitting `allow` permits every scheme and method registered on the gateway. * `allow: ["x402:exact"]` restricts the route to only the `exact` scheme. * `allow: []` is the deny-all sentinel — it denies everything. * **`pin`** — maps a `":"` key to `{ capturesAt: "request" | "response" }`, forcing that scheme to one-phase (`"request"`) or two-phase (`"response"`) capture regardless of what the matched handler is otherwise capable of. A safe, common pattern — pin the rug-pullable `exact` scheme to one-phase so there is no authorize-then-capture window: ```yaml theme={null} paths: /v1/cheap: get: x-faremeter-pricing: rules: - match: "true" rates: flat: 1000 x-faremeter-policy: pin: "x402:exact": capturesAt: "request" # force one-phase; no rug-pull window ``` A few rules to keep in mind: * **Operation-level only.** Unlike `x-faremeter-pricing`, which can also be declared at the path or document level, `x-faremeter-policy` is read only on individual operations. Declaring it on a path item or on the document is rejected loudly at parse time — it does not silently inherit downward. * **Pinning to two-phase has prerequisites.** Pinning a scheme to `capturesAt: "response"` requires both that the matched handler can authorize and that every pricing rule on the operation defines `authorize`. Pinning to `capturesAt: "request"` (one-phase) is always safe. * **Validated at construction.** The policy is cross-checked against the registered handler set when the gateway handler is built, so a misconfigured spec never starts serving requests. Caught at construction: an `allow` or `pin` entry naming a scheme or method the gateway does not serve; a `pin` entry that is not also listed in `allow`; and a `"response"` pin against a handler that cannot authorize or a route whose rules lack `authorize`. Each error names the operation, the offending entry, and the schemes the gateway actually supports. ## The publishing flow Your API runs wherever it already runs. The marketplace does not host your code. Through the operator's control plane (UI or API), register a tenant with your backend URL, your OpenAPI spec, and your settlement wallet address. The control plane stores the configuration and pushes it to API nodes. The marketplace assigns your tenant a routable URL (for example, `your-tenant.example-marketplace.dev`). All public traffic goes there; the proxy validates payment and forwards to your backend. The discovery service is what makes your API findable. Once your tenant is active, list it so the OpenAPI spec, pricing, and proxy URL appear in search results. Consumers query the discovery API to find you. Each paid request settles before reaching your backend. Funds land in your wallet on the cadence the operator's facilitator settles at. ## Where to publish | Goal | Where | | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | | Get listed quickly with no operations work | Use a [hosted marketplace](https://corbits.dev). Sign-up flow, dashboard, hosted facilitator. | | Run a marketplace with full control | Deploy the [marketplace OSS](https://github.com/faremeter/marketplace). See [self-hosting](/marketplace/self-hosting). | | Charge for a single API on your own server | Skip the marketplace entirely — use [`@faremeter/middleware`](/server/middleware-overview). | Specific tenant-onboarding steps (UI flows, request payloads, listing requirements) depend on which marketplace you publish to. Consult the operator's documentation for exact procedures. The Faremeter docs describe the OSS pieces; the operator describes their product. ## What's next The pricing extensions and config the API nodes generate from your spec. What `exact`, `charge`, and `flex` mean when you pick a pricing scheme. How the marketplace settles your paid requests on-chain. Run the marketplace stack yourself.