# Service Router > Pay-per-call access to APIs for AI agents. One account and one payment key pay any service listed here, with credits: a prepaid USD balance, with no on-chain fee per call. Agents without an account can pay each call with x402 or MPP instead. Sellers list an API and get paid per call. Every service is called at `https://pay.servicerouter.ai/service//`. A call without payment answers `402 Payment Required`, listing every way to pay: credits, x402 (USDC on Base and Solana), and MPP (stablecoins on Tempo). Credits are the default: sub-cent prices work, and nothing is signed per call. ## Start with credits Ask your user before each of these steps. 1. Sign up: `curl -X POST https://api.servicerouter.ai/v1/accounts`. The answer has a `masterKey`. Save it at once in a file only your user can read (`chmod 600`), and never paste it into a chat, a log, or a URL. 2. Tell your user that a lost master key can't be recovered: there is no email recovery yet. Ask them to keep a copy somewhere safe. 3. Create a payment key with limits your user agrees to, and use only that key for calls. Keep the master key with your user: ```sh curl -X POST https://api.servicerouter.ai/v1/keys \ -H "Authorization: Bearer $SERVICEROUTER_MASTER_KEY" \ -H "Content-Type: application/json" \ -d '{"label": "my-agent", "dailyBudget": "5", "maxPrice": "0.05"}' ``` The answer's `key` is shown once. Limits: `dailyBudget` (USD a day, $5 by default), `allowance` (USD in total), `maxPrice` (USD per call), and `expiresAt`. 4. Top up with USDC on Stellar: coming soon. Until then, pay each call with x402 or MPP instead. ## Call a service ```sh curl https://pay.servicerouter.ai/service// -H "Authorization: Bearer $SERVICEROUTER_PAYMENT_KEY" ``` - A paid answer carries `Servicerouter-Receipt: id="pay_…", amount="0.001", currency="USD"`. You pay only for `2xx` answers. - `GET https://pay.servicerouter.ai/_/key` with the payment key shows its limits, what it spent, and what's left. - `https://api.servicerouter.ai/v1/balance` and `https://api.servicerouter.ai/v1/payments` take the master key. - Errors are `{"error": {"code", "message"}}`: `insufficient_balance`, `key_budget_exceeded`, `key_allowance_exceeded`, `key_price_limit` (`402`); `invalid_key`, `wrong_key_type` for a master key (`401`); `rate_limited` (`429`, with `Retry-After`); `upstream_unavailable` (`503`, not charged). ## Pay without an account - **x402:** the `402` has a `PAYMENT-REQUIRED` header (x402 v2). Sign one of its options with an x402 client and retry with `PAYMENT-SIGNATURE`. The answer carries `PAYMENT-RESPONSE`. - **MPP:** the `402` has a `WWW-Authenticate: Payment` Tempo charge. Sign it in pull mode with an MPP client, such as `mppx`, and retry with `Authorization: Payment …`. The answer carries `Payment-Receipt`. Send the retry at once: the signed transaction expires within about 25 seconds. Either way, the payment settles only after a `2xx` answer. A failed call costs nothing. ## Pay any x402 or MPP API Put `https://pay.servicerouter.ai/` in front of a paid API's URL, without `https://`: `https://pay.servicerouter.ai/api.example.com/v1/pools` calls `https://api.example.com/v1/pools`. The API doesn't need to be listed here. Service Router pays it in its own protocol, x402 on Base or Solana, or MPP on Tempo, and returns its answer. You pay Service Router the quote, the API's price plus any routing fee, in any way above: a payment key in one request, or the options of its `402`, such as x402 with USDC on Base. `GET https://pay.servicerouter.ai/_/check?url=` quotes a link without paying. A failed call costs nothing. ## Find services - [The catalog](https://servicerouter.ai/discover.md): every service, with prices, payment methods, and stats. Filter with `?category=`, `q=`, `method=`, `maxPrice=`, and `sort=`. - Each service has its own instructions: `llms.txt`, an Agent Skill, and an OpenAPI document whose server is its pay URL. Its page links them: `https://servicerouter.ai/discover/.md`. ## Skills - [Buyer skill](https://servicerouter.ai/skills/servicerouter-buyer/SKILL.md): everything above, step by step. - [Seller skill](https://servicerouter.ai/skills/servicerouter-seller/SKILL.md): list an API and get paid per call, with plain HTTP calls. ## Optional - [Everything in one file](https://servicerouter.ai/llms-full.txt): this guide, both skills, and the catalog. - [For agents](https://servicerouter.ai/agents.md): what agents can read here. --- --- name: servicerouter-buyer description: Pay for API calls through Service Router with credits, x402, or MPP. Use when the user wants an agent to call a paid API listed on Service Router, to sign up, to create a payment key with limits, or to check spending. --- # Service Router for buyers Service Router lets an agent call paid APIs, paying per call. Credits, a prepaid USD balance, are the default. Every listed service is at `https://pay.servicerouter.ai/service//`. Ask the user before you sign up, create a key, or spend anything. ## 1. Sign up once ```sh curl -s -X POST https://api.servicerouter.ai/v1/accounts > servicerouter-account.json chmod 600 servicerouter-account.json ``` The answer's `masterKey` controls the account. Keep it in that file, readable only by the user. Never print it, paste it into a chat, or put it in a URL. Tell the user: a lost master key can't be recovered, because there is no email recovery yet. Ask them to keep a copy safe. ## 2. Create a payment key for the agent Agents call with a payment key, never the master key. Agree on its limits with the user first. ```sh MASTER_KEY=$(jq -r .masterKey servicerouter-account.json) curl -s -X POST https://api.servicerouter.ai/v1/keys \ -H "Authorization: Bearer $MASTER_KEY" \ -H "Content-Type: application/json" \ -d '{"label": "my-agent", "dailyBudget": "5", "allowance": "20", "maxPrice": "0.05"}' ``` The `key` in the answer is shown once: store it like the master key. `GET https://api.servicerouter.ai/v1/keys` lists keys and what each spent. `PATCH https://api.servicerouter.ai/v1/keys/` changes limits. `DELETE https://api.servicerouter.ai/v1/keys/` revokes one. ## 3. Top up Top-ups with USDC on Stellar are coming soon. `GET https://api.servicerouter.ai/v1/balance` (master key) shows the balance. Until then, pay per call with x402 or MPP (step 5). ## 4. Find and call a service - The catalog: `https://servicerouter.ai/discover.md`, filtered with `?q=`, `category=`, `method=`, `maxPrice=`, and `sort=popular|price|newest|success`. - A service: `https://servicerouter.ai/discover/.md` lists its routes and prices, and links its `llms.txt`, Agent Skill, and OpenAPI document. ```sh curl https://pay.servicerouter.ai/service// -H "Authorization: Bearer $SERVICEROUTER_PAYMENT_KEY" ``` - Only `2xx` answers are charged. Each carries `Servicerouter-Receipt` with the payment ID and amount. - `GET https://pay.servicerouter.ai/_/key` (payment key) shows the key's limits and what's left. - `402` codes: `insufficient_balance` (top up), `key_budget_exceeded` (wait for midnight UTC, or ask the user to raise it), `key_allowance_exceeded`, `key_price_limit`. - `401 wrong_key_type`: a master key was sent. Use the payment key. - `429 rate_limited`: wait for `Retry-After` seconds. - `503 upstream_unavailable`: the service failed. You weren't charged. ## 5. Without an account: x402 or MPP A call without a credential answers `402` with every option: - `PAYMENT-REQUIRED`: x402 v2. Sign an option with an x402 client, and retry with `PAYMENT-SIGNATURE`. - `WWW-Authenticate: Payment`: an MPP Tempo charge. Sign it in pull mode, with `mppx` for example, and retry with `Authorization: Payment …` at once: the transaction expires within about 25 seconds. Payment settles only after a `2xx` answer. ## 6. Any x402 or MPP API, listed or not Put `https://pay.servicerouter.ai/` in front of the API's URL, without `https://`: ```sh curl https://pay.servicerouter.ai/api.example.com/v1/pools -H "Authorization: Bearer $SERVICEROUTER_PAYMENT_KEY" ``` Service Router pays the API in its own protocol, x402 on Base or Solana, or MPP on Tempo, and returns its answer. You pay the quote, the API's price plus any routing fee, with the payment key, or with an option of the `402` (step 5), such as x402 with USDC on Base. `GET https://pay.servicerouter.ai/_/check?url=` quotes a link without paying. `502 unsupported_payment`: the API asks for no payment Service Router makes. You weren't charged. --- --- name: servicerouter-seller description: List an API on Service Router and get paid per call by agents. Use when the user wants to sell access to their API, write or submit a Service Router config, rotate upstream secrets, roll back a revision, or check earnings. --- # Service Router for sellers Service Router sells per-call access to an HTTP API. Agents call `https://pay.servicerouter.ai/service//` and pay with credits, x402, or MPP. The platform forwards each paid call to the upstream with the seller's credentials, which agents never see, and pays the seller. Show the user the config before you submit it. Never print secret values. ## 1. Sign up once ```sh curl -s -X POST https://api.servicerouter.ai/v1/accounts > servicerouter-account.json chmod 600 servicerouter-account.json ``` The `masterKey` controls the account and its earnings. Keep it in that file. A lost master key can't be recovered yet. ## 2. Write the config One YAML file describes the service, its upstream, its prices, and its payout: ```yaml servicerouter: version: "1" service: id: my-prices # [a-z0-9-], unique, in the URL forever title: My Prices summary: Live token prices by symbol description: | The latest price, 24-hour change, and volume for any token symbol. category: crypto/prices # One ID of the catalog's categories: `GET https://api.servicerouter.ai/v1/catalog` lists them tags: [prices, tokens] discoverable: true # Listed in the x402 Bazaar. false keeps it out payouts: default: asset: stellar-usdc # Paid out in USDC on Stellar, coming soon address: G... # Your Stellar account payments: default: amount: "0.001" # USD per call upstreams: - baseUrl: https://api.example.com openapi: https://api.example.com/openapi.json # Or an inline `paths` object auth: main-key credentials: main-key: type: http scheme: bearer # Authorization: Bearer secret: upstream-key # A name: the value is sent separately ``` - Each operation of the OpenAPI document becomes a route at the same path. `routes.` sets a route's own `payment`, a `target` path, or `enabled: false`. - An amount of `"0"` makes a route free. - `service.discoverable` (default `true`) lists each paid route in the x402 Bazaar, Coinbase's catalog of x402 APIs, once a payment for it settles through Coinbase's facilitator: its 402 carries the route's description, input and output schemas, and response example from your OpenAPI document. `discoverable: false` keeps the service out of it. Changing it makes a new revision, like any change. ## 3. Submit it with its secrets ```sh MASTER_KEY=$(jq -r .masterKey servicerouter-account.json) jq -n --rawfile config service.yaml --arg key "$UPSTREAM_KEY" \ '{config: $config, secrets: {"upstream-key": $key}}' | curl -s -X PUT https://api.servicerouter.ai/v1/services/my-prices \ -H "Authorization: Bearer $MASTER_KEY" \ -H "Content-Type: application/json" \ --data-binary @- ``` - `201` creates the service, `200` updates it, and each change is a new revision. - `400 invalid_config` lists every problem with its path, line, and column. Fix them and submit again. - Secrets are sealed and bound to the host they go to. A config with no new secrets can be sent as YAML, with `Content-Type: application/yaml`. ## 4. Check and manage it - `GET https://api.servicerouter.ai/v1/services`: your services. `GET https://api.servicerouter.ai/v1/services/my-prices`: one service. - `GET …/revisions` lists revisions. `POST …/rollback` with `{"revision": 3}` makes an older one active. - `PUT …/secrets/` with `{"value": "…"}` rotates one secret. - `GET …/earnings`: calls, earnings by payment method, the fee, and pending payout. - Its public page: `https://servicerouter.ai/discover/my-prices`. ## 5. Prove you own the upstream Before a service goes live, each upstream host serves `/.well-known/servicerouter.json` with the service's token. `GET https://api.servicerouter.ai/v1/services//status` shows what's missing. A change of payout address waits until every host lists its confirmation token. This check is arriving: follow the status endpoint's answer. ## 6. Get paid Payouts in USDC on Stellar to the payout address are coming soon. Until then, earnings accrue and nothing is paid out. Agents find the service in the catalog, in its generated `llms.txt`, Agent Skill, and OpenAPI document, and in the x402 Bazaar unless `discoverable` is `false`. --- # Discover services Every service listed on Service Router, called at `https://pay.servicerouter.ai/service//` and paid per call. Filter with `?category=`, `q=`, `method=` (credits, x402, mpp), `maxPrice=` (USD), and `sort=` (popular, price, newest, success). ## Categories - [Blockchain](https://servicerouter.ai/discover.md?category=blockchain) (`blockchain`): 1 - [Node RPC](https://servicerouter.ai/discover.md?category=blockchain/rpc) (`blockchain/rpc`): 1 ## Services - [NOWNodes](https://servicerouter.ai/discover/nownodes.md): Blockchain JSON-RPC and explorer API for Ethereum, Base, Solana, and Bitcoin. From $0.0005 a call; Credits, x402, MPP; 12 calls in 30 days, 100.0% success. - [pro-api.coinmarketcap.com/x402/v3/cryptocurrency/quotes/latest](https://pay.servicerouter.ai/pro-api.coinmarketcap.com/x402/v3/cryptocurrency/quotes/latest) (unverified): A paid API that Service Router routes payments to. Unverified: its owner hasn't registered it. From $0.01 a call; Credits, x402, MPP. - [x402.sniperx.fun/api/v1/token/price](https://pay.servicerouter.ai/x402.sniperx.fun/api/v1/token/price) (unverified): A paid API that Service Router routes payments to. Unverified: its owner hasn't registered it. From $0.01 a call; Credits, x402, MPP.