---
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.agents.bakingbad.dev/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.agents.bakingbad.dev/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.agents.bakingbad.dev/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.agents.bakingbad.dev/v1/keys` lists keys and what each spent. `PATCH https://api-servicerouter.agents.bakingbad.dev/v1/keys/<id>` changes limits. `DELETE https://api-servicerouter.agents.bakingbad.dev/v1/keys/<id>` revokes one.

## 3. Top up

`GET https://api-servicerouter.agents.bakingbad.dev/v1/account` (master key) returns `topupUrl`. Give it to the user: it shows a deposit address for USDM on Cardano. Credits arrive once the deposit confirms. `GET https://api-servicerouter.agents.bakingbad.dev/v1/balance` shows the balance. While `topupUrl` is null, deposits aren't open yet: pay per call with x402 or MPP (step 5).

## 4. Find and call a service

- The catalog: `https://servicerouter.agents.bakingbad.dev/discover.md`, filtered with `?q=`, `category=`, `method=`, `maxPrice=`, and `sort=popular|price|newest|success`.
- A service: `https://servicerouter.agents.bakingbad.dev/discover/<service-id>.md` lists its routes and prices, and links its `llms.txt`, Agent Skill, and OpenAPI document.

```sh
curl https://pay-servicerouter.agents.bakingbad.dev/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.agents.bakingbad.dev/_/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.