> ## 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.

# Errors

> What 400, 401, 402, 422, InsufficientCapacity, and 5xx responses mean, whether a payment settled, and how to recover.

Errors are JSON with a `detail` field. Only a 2xx response settles an x402 payment, so every error on this page is free.

| Status | Meaning | Settled | What to do |
| :- | :- | :- | :- |
| `400` | The request is valid JSON but cannot be served: unknown market, bad constraint, unsupported chain or token, or `InsufficientCapacity` | No | Read `detail`, fix the request |
| `401` | Partner headers are present but wrong, or missing while x402 is off | No | Check both headers. A wrong key never falls back to payment |
| `402` | Payment needed, invalid, for the wrong amount, or settlement failed | No | Sign the offer in `PAYMENT-REQUIRED` and retry |
| `422` | The body does not match the schema, or `current_allocations` sums above `total_capital` | No | Read the field errors in `detail` |
| `500` | Unexpected server error | No | Retry with backoff |
| `503` | A feature is not enabled, for example monitor sessions | No | Use partner headers or try later |

## 400

Constraint mistakes name the expected parameters:

```json theme={null}
{
  "detail": "Invalid max_amount_per_protocol constraint: 'max_ratio' must be greater than 0 and at most 1. Expected params: protocol (market name), max_ratio (fraction of total_capital, greater than 0 and at most 1; 0.4 means 40%)"
}
```

### Insufficient capacity

Internally this is `InsufficientCapacity`. The [risk rules](https://docs.si.ampli.net/risk-rules.md) and your constraints leave less room than `total_capital`. The detail says how much fits:

```json theme={null}
{
  "detail": "Optimization failed: The liquidity and health rules allow 3120000000000 of 5000000000000 to be placed across the requested protocols. Lower total_capital or add protocols."
}
```

Here 5,000,000 USDC (`5000000000000`) was requested and 3,120,000 USDC (`3120000000000`) fits. Lower `total_capital`, add markets from the [market list](https://docs.si.ampli.net/markets.md), or relax a constraint. The service never returns a partial plan.

## 401

```json theme={null}
{ "detail": "Invalid or missing partner API key" }
```

## 402

The body and the base64 `PAYMENT-REQUIRED` header carry the same offer. `error` explains why:

| `error` | Cause |
| :- | :- |
| `PAYMENT-SIGNATURE header is required` | First call, no payment yet |
| `PAYMENT-SIGNATURE is not a valid base64 x402 payload` | The header could not be decoded |
| `Only x402 version 2 payments are accepted` | A version 1 payload was sent |
| `Payment does not match the current price or terms for this call` | Wrong amount, asset, network, or recipient. The price may have changed |
| `Payment settlement failed: ...` | Verified, ran, but did not settle. Sign a new payload |

See [Authentication and payments](https://docs.si.ampli.net/authentication.md) for the full offer.

## 422

```json theme={null}
{
  "detail": [
    {
      "type": "value_error",
      "loc": ["body"],
      "msg": "Value error, current_allocations sum to 1200000000, which exceeds total_capital 1000000000"
    }
  ]
}
```

## Over MCP

A failed tool call returns `isError: true` with the same body in `structuredContent`: the offer for a payment problem, or `{"status": 400, "detail": "..."}` for anything else. See [API MCP](https://docs.si.ampli.net/api-mcp.md).


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