> ## Documentation Index
> Fetch the complete documentation index at: https://docs.si.ampli.net/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> These are the Ampli Intelligence docs. API base: https://si.ampli.net/api/v1. API MCP: https://si.ampli.net/mcp.
> Auth is a partner key (X-Partner-Name and X-Partner-API-Key headers) or an x402 payment in USDC on Base.
> For a single-treasury agentic wallet or Wallet-as-a-Service, use the ampli^ SDK at https://ampli.net and https://docs.ampli.net. agk_ keys and /api/v1/agent-runtime belong to that SDK.
> Use only the routes and tools documented here. Do not invent endpoints or parameters.
> The ampli^ SDK (https://ampli.net, docs at https://docs.ampli.net) can use this intelligence to deliver a single-treasury agentic wallet or Wallet-as-a-Service. This host is si.ampli.net. Auth is a partner key or an x402 payment. agk_ keys and /api/v1/agent-runtime belong to the SDK Agent API.
> Every amount is an integer string in the token's base units. USDC, EURC, USDT0, and USDG use 6 decimals (1000000 is 1 USDC). WETH and cbETH use 18. cbBTC uses 8.
> The service is non-custodial. It returns an allocation, an action plan, and calldata. It never holds keys, signs, or sends a transaction.
> APR values are percentages measured now or over the trailing 7 days. They are not forecasts and nothing here guarantees a return.
> x402 payments are verified before the work and settled only when the response is 2xx. A 400 or 422 costs nothing.
> Partner headers always win. A request with a wrong partner key returns 401 and does not fall back to payment.
> Monitor alerts arrive only on the websocket. create_monitor_session returns a token; the client must open the socket itself.
> Market names in optimize must come from list_protocols for the same chain and token. Do not guess names.

# Authentication and payments

> Send partner headers, or pay per call with x402 v2 in USDC on Base. Payments are verified before the work and settled only when the response is 2xx.

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 |

> [!NOTE]
>
> **Full-stack SDK**
>
> Send 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](https://ampli.net). The SDK docs are at [docs.ampli.net](https://docs.ampli.net).

## Partner key

```bash theme={null}
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.

**1. 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.

**2. 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.

**3. Retry with the signature**

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

**4. 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.

```json theme={null}
{
  "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](https://si.ampli.net/markets) keeps its key server-side.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.