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

# Quickstart

> Make one optimize call with a partner key, then make the same call paid per request with x402 in USDC on Base.

This page rebalances 1,000 USDC on Base across seven lending markets. The request is identical for both auth methods; only the headers change.

## The request

Amounts are base units. USDC on Base has 6 decimals, so `1000000000` is 1,000 USDC and `500000000` is 500 USDC.

```json theme={null}
{
  "total_capital": "1000000000",
  "token_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "current_allocations": { "aave": "500000000", "compound": "500000000" },
  "protocols": ["aave", "compound", "moonwell", "fluid", "euler_usdc", "spark", "superform"],
  "wallet_address": "0xYourWallet"
}
```

Save it as `request.json`. The market names in `protocols` must come from the [market list](https://docs.si.ampli.net/markets.md) for the same chain and token.

## With a partner key

**1. Send the call**

```bash theme={null}
curl -s https://si.ampli.net/api/v1/optimizer/8453/optimize \
  -H "Content-Type: application/json" \
  -H "X-Partner-Name: your-partner-name" \
  -H "X-Partner-API-Key: $AMPLI_PARTNER_API_KEY" \
  -d @request.json
```

**2. Read the plan**

The response has three parts: `optimization_result` (the target allocation and APR before and after), `action_plan` (withdrawals first, then deposits), and `calldata` (one entry per transaction, in order). See [Optimize](https://docs.si.ampli.net/optimize.md) for every field.

**3. Execute with your own wallet**

Check the plan, then sign and send each `calldata` entry in order from `wallet_address`. Ampli never signs or sends anything.

## With x402

Leave out the partner headers. The first response is `402 Payment Required` with a `PAYMENT-REQUIRED` header that carries the price in USDC base units on Base (`eip155:8453`). An x402 client signs an EIP-3009 authorization and retries with `PAYMENT-SIGNATURE`. It needs no gas and no prior approval, only USDC on Base in the paying wallet.

> [tab] TypeScript
>
> ```bash theme={null}
> pnpm add @x402/fetch @x402/evm viem
> ```
>
> ```ts theme={null}
> import { readFileSync } from "node:fs";
> import { decodePaymentResponseHeader, wrapFetchWithPaymentFromConfig } from "@x402/fetch";
> import { ExactEvmScheme } from "@x402/evm";
> import { privateKeyToAccount } from "viem/accounts";
>
> // The paying wallet's own signer. Ampli never sees this key.
> const payer = privateKeyToAccount(process.env.PAYER_PRIVATE_KEY as `0x${string}`);
>
> const fetchWithPayment = wrapFetchWithPaymentFromConfig(fetch, {
>   schemes: [{ network: "eip155:8453", client: new ExactEvmScheme(payer) }],
> });
>
> const response = await fetchWithPayment("https://si.ampli.net/api/v1/optimizer/8453/optimize", {
>   method: "POST",
>   headers: { "Content-Type": "application/json" },
>   body: readFileSync("request.json", "utf8"),
> });
>
> const plan = await response.json();
> const receipt = response.headers.get("PAYMENT-RESPONSE");
> console.log(plan.action_plan, receipt ? decodePaymentResponseHeader(receipt) : null);
> ```

> [tab] Raw HTTP
>
> ```bash theme={null}
> # 1. Ask without payment. Expect 402 and a PAYMENT-REQUIRED header (base64 JSON).
> curl -si https://si.ampli.net/api/v1/optimizer/8453/optimize \
>   -H "Content-Type: application/json" -d @request.json
>
> # 2. Sign the offer with an x402 client, then retry with the signed payload.
> curl -si https://si.ampli.net/api/v1/optimizer/8453/optimize \
>   -H "Content-Type: application/json" \
>   -H "PAYMENT-SIGNATURE: <base64 payment payload>" \
>   -d @request.json
> ```

> [!TIP]
>
> **Mistakes are free**
>
> The payment is verified before the work and settled only on a 2xx response. A `400` for a bad constraint or a `422` for an over-allocated book costs nothing.

## Next

* [Authentication and payments](https://docs.si.ampli.net/authentication.md) for the full 402 offer and receipt.
* [Risk rules](https://docs.si.ampli.net/risk-rules.md) to understand why a market got less than you expected.
* [API MCP](https://docs.si.ampli.net/api-mcp.md) to call the same thing as an MCP tool.


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