Agent API — what your agent should know

This page documents the contract a third-party AI agent uses to talk to a AgentRail-protected site. The principles: discover via the merchant's catalog endpoint (e.g. /api/catalog), respect the price headers, pay via one of three rails, retry. The endpoints below are illustrative — for runnable, real implementations see the /demos directory of the repo.

Pricing table

Illustrative example merchant policy — this is what a merchant configures, not AgentRail’s own pricing (see Pricing for that).

Resource	Tier	Price	Allowed purposes
`/api/catalog`	free	$0.00	any
`/api/products`	metered	$0.05 / call	browsing, answer, search-index
`/api/products/:sku`	metered	$0.05 / call	browsing, answer, search-index
`/content/reports/:id`	premium	$0.25	browsing, answer
`/content/articles/:slug`	metered	$0.05 / call	browsing, answer, search-index
`/content/reports/premium/:id`	premium	$0.75	browsing, answer
`/api/export/full`	premium	$5.00	browsing, answer

Training-purpose access is denied for premium resources by default — the merchant configures this in the dashboard.

The agent contract

Identifying yourself

Send your identity in well-known headers so the merchant can apply the right policy and you get the right price.

User-Agent: Claude-Web/1.0
X-Agent-Identity: anthropic/claude
X-Agent-Purpose: browsing
X-Agent-Operator: acme-research-org
Accept: application/json

Discovering resources

The catalog endpoint lists every exposed resource, its tier, its price, and what purposes are allowed.

# discover
$ curl "https://example-merchant.com/api/catalog" \
    -H "X-Agent-Identity: anthropic/claude"

{
  "merchant": "Example Merchant",
  "resources": [...]
}

Paying with HTTP 402

Paid resources return 402 Payment Required with price headers. The agent picks a supported payment rail, gets a receipt, and retries with X-Payment-Receipt.

# 1. First call — no payment yet
$ curl -i "https://example-merchant.com/content/reports/q1-margins" \
    -H "X-Agent-Identity: anthropic/claude" \
    -H "X-Agent-Purpose: browsing"

HTTP/1.1 402 Payment Required
X-Price-Cents: 25
X-Payment-Methods: demo,ap2,x402
{"error": "payment_required", "price_cents": 25, ...}

# 2. Mint a receipt via the AP2 facilitator
$ curl "https://example-merchant.com/payments/ap2" \
    -H "Content-Type: application/json" \
    -d '{"amount_cents": 25}'

{"receipt": "demo:25:ab12cd34", ...}

# 3. Retry with the receipt
$ curl "https://example-merchant.com/content/reports/q1-margins" \
    -H "X-Agent-Identity: anthropic/claude" \
    -H "X-Agent-Purpose: browsing" \
    -H "X-Payment-Receipt: demo:25:ab12cd34"

HTTP/1.1 200 OK
{"report": "Cloud margins, Q1 2026", "headline": "Hyperscaler margins diverged again...", ...}

Supported payment rails

AP2

Google's Agent Payments Protocol. Signed mandates, multi-rail (cards, ACH, stablecoins).

x402

Coinbase's HTTP 402 spec. On-chain micropayments via USDC, settled by an x402 facilitator.

Bedrock Payments

AWS Bedrock AgentCore payment APIs — for agents already running in the Bedrock environment.