Authentication and payments

Every paid route and every paid MCP tool accepts one of two credentials. Pick one per request.

Method	Send	Cost	Who it is for
Partner key	`X-Partner-Name` and `X-Partner-API-Key` headers	Covered by your agreement	Contracted partners
x402	No partner headers; `PAYMENT-SIGNATURE` on the retry	Per call, in USDC on Base	Anyone, including autonomous agents

Full-stack SDKSend a partner key or an x402 payment. agk_ wallet keys belong to the ampli^ SDK, which can use this intelligence to deliver a single-treasury agentic wallet or Wallet-as-a-Service. Start at ampli.net. The SDK docs are at docs.ampli.net.

Partner key

curl -s https://si.ampli.net/api/v1/8453/0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913/protocols \
  -H "X-Partner-Name: your-partner-name" \
  -H "X-Partner-API-Key: $AMPLI_PARTNER_API_KEY"

Keys are shown once at creation and stored only as hashes. Ampli can rotate a key on request.
Partner headers always win. If either header is present, the request is treated as a partner request. A wrong or missing value returns 401 and does not fall back to payment.
Keep the key on a server. Never ship it in a browser bundle or a mobile app.

x402

x402 uses HTTP status 402 Payment Required. Ampli speaks x402 version 2 with the exact scheme on Base mainnet (eip155:8453), paid in USDC.

Call without payment

Send the request with no partner headers. The server answers 402 with a PAYMENT-REQUIRED header: base64-encoded JSON listing what it accepts. The same JSON is in the response body.

Sign

The client picks the offer, then signs an EIP-3009 transferWithAuthorization for that exact amount to the listed payTo address. Signing costs no gas and needs no approval transaction.

Retry with the signature

Repeat the identical request with the signed payload, base64-encoded, in PAYMENT-SIGNATURE.

Get the result and receipt

The server verifies the payment, runs the request, settles on-chain, and returns the result with a PAYMENT-RESPONSE header that carries the settlement transaction.

The offer

Decoded PAYMENT-REQUIRED, with example values. The live price is always the one in the offer you receive.

{
  "x402Version": 2,
  "error": "PAYMENT-SIGNATURE header is required",
  "resource": {
    "url": "https://si.ampli.net/api/v1/optimizer/8453/optimize",
    "description": "Allocation, plan and calldata",
    "mimeType": "application/json"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "amount": "10000",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0xAmpliTreasury",
      "maxTimeoutSeconds": 120,
      "extra": { "name": "USD Coin", "version": "2" }
    }
  ]
}

amount is in USDC base units: 10000 is 0.01 USDC in this example.

Prices

Route	MCP tool	Unit
`POST /optimizer/{chain_id}/optimize`	`optimize`	per call
`GET /{chain_id}/{token_address}/protocols`	`list_protocols`	per call
`POST /protocols/health`	`protocol_health`	per asset in the request
`POST /monitor/sessions`	`create_monitor_session`	per hour of the window

A health call for three assets costs three units. A six-hour monitor session costs six. The offer already contains the total.

When a payment settles

Verify first. The signature is checked with the facilitator before any work runs. An invalid or mismatched payment gets a fresh 402 with the reason in error.
Settle on success only. Settlement happens after the handler returns a 2xx. A 400, 422, or 500 never settles, so validation mistakes cost nothing.
One payment, one call. A signed payload pays for the request it was sent with. If settlement fails, the response is a new 402; sign a new payload rather than resending the old one.
Price changes. If the price changed between the offer and the retry, the server answers 402 with the current offer.

Which credential to use

A backend for your own product: use a partner key.
An agent that must work without a human signing up: use x402.
A browser app: call your own backend, which holds the partner key. See how the live markets page keeps its key server-side.

Get started

API

Agents

Reference

Partner key

x402

The offer

Prices

When a payment settles

Which credential to use