---
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/<service-id>/<path>`.

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/<id>` changes limits. `DELETE https://api.servicerouter.ai/v1/keys/<id>` 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/<service-id>.md` lists its routes and prices, and links its `llms.txt`, Agent Skill, and OpenAPI document.

```sh
curl https://pay.servicerouter.ai/service/<service-id>/<path> -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=<link>` quotes a link without paying. `502 unsupported_payment`: the API asks for no payment Service Router makes. You weren't charged.
