Provider protocol

Providers sell answers to requests. You implement two HTTPS endpoints, register them, and get paid in USDC for every fill you win.

Register

Sign in on the Provider page and enter your name, payout wallet, the request types you serve, a quote URL and a fulfill URL. Both URLs must be HTTPS.

1. Quote endpoint

For every order of a type you serve, we send:

http
POST https://your-api.example.com/quote
Content-Type: application/json

{
  "order_id": "ord_…",
  "type": "price.spot",
  "params": { "mint": "So11111111111111111111111111111111111111112" },
  "max_price": "0.004000",
  "currency": "USDC"
}

Answer within 2.5 seconds with your price, or 204 No Content to decline:

json
{ "price": "0.0018", "ttl_ms": 30000 }

price is in USDC with up to 6 decimals. Use ttl_ms (max 300000) or an ISO expires_at to say how long the quote holds.

The five checks

CheckPasses when
Price within max0 < price ≤ max_price
Provider activeYour status is Active
Serves the typeThe type is in your declared list
Quote not expiredYour expiry is in the future when checked
HTTPS endpointYour quote endpoint answered with 2xx and your fulfill URL is HTTPS

The lowest passing quote wins. On a tie, independent providers beat StellarBook Labs, then the faster quote wins.

2. Fulfill endpoint

After the buyer pays you and we verify the transfer, we call your fulfill URL with the signed receipt:

http
POST https://your-api.example.com/fulfill
Content-Type: application/json

{
  "type": "price.spot",
  "params": { "mint": "So11111111111111111111111111111111111111112" },
  "receipt": { "payload": { … }, "signature": "…", "signer": "…" }
}

Verify the receipt (see Signed receipts), check that payload.provider is your slug and payload.recipient is your wallet, then return your result as JSON within 15 seconds. Deliver each fill_id at most once per buyer, but answer retries of the same fill with the same result.

Getting paid

The buyer pays your payout wallet directly. There is nothing to withdraw and no fee is taken. Your quote pass rate, latency and settle rate are public on the Providers page.