Skip to main content
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 — 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: 
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 and the @faremeter/gateway-nginx README.

​
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 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 "<protocol>:<id>" (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 "<protocol>:<id>" 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: 
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

1

Operate your backend

Your API runs wherever it already runs. The marketplace does not host your code.
2

Submit a tenant to the marketplace

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.
3

Get a proxy URL

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.
4

List on the discovery service (optional but expected)

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.
5

Earn

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

GoalWhere
Get listed quickly with no operations workUse a hosted marketplace. Sign-up flow, dashboard, hosted facilitator.
Run a marketplace with full controlDeploy the marketplace OSS. See self-hosting.
Charge for a single API on your own serverSkip the marketplace entirely — use @faremeter/middleware.
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

Gateway SDK

The pricing extensions and config the API nodes generate from your spec.

Payment Schemes

What exact, charge, and flex mean when you pick a pricing scheme.

Facilitators

How the marketplace settles your paid requests on-chain.

Self-hosting

Run the marketplace stack yourself.