Skip to main content

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.

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.

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