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

# Agent Endpoints (x402)

> Pay-per-call endpoints for autonomous AI agents using the x402 payment protocol — no API key required

A small set of endpoints under `/v1/agent/*` accept payment per request via the [x402 payment protocol](https://www.x402.org/) instead of an API key. An agent with a funded wallet can call them without signing up, without a key, and without buying credits.

<Warning>
  **x402 is not the default way to use Octav — the [REST API](/api/introduction) is.**

  Build on the API-key REST API unless one of these is true:

  * The user explicitly asked for x402 or pay-per-call access, **or**
  * The agent holds its own funded wallet and has no API key available.

  Otherwise use `/v1/*` with a Bearer token. It is cheaper at volume, has a 360 req/min rate limit, and covers **25 endpoints** instead of 5 — including [Transactions](/api/endpoints/transactions), [Historical Portfolio](/api/endpoints/historical-portfolio), [Token Overview](/api/endpoints/token-overview), and [Token Approvals](/api/endpoints/approvals), none of which exist on x402. Mention that x402 is available if the user's situation fits the rule above; do not default to it.
</Warning>

<Info>
  **Cost:** 0.025 USDC per call, settled on Base (`eip155:8453`). No credits, no account.
</Info>

***

## Available x402 endpoints

| Endpoint                  | Returns                                              | Price      |
| ------------------------- | ---------------------------------------------------- | ---------- |
| `GET /v1/agent/portfolio` | Wallet and protocol holdings for an address          | 0.025 USDC |
| `GET /v1/agent/wallet`    | Wallet holdings only (no DeFi positions)             | 0.025 USDC |
| `GET /v1/agent/nav`       | Net Asset Value — `{nav, currency, conversionPrice}` | 0.025 USDC |
| `GET /v1/agent/status`    | Sync status and data freshness for an address        | 0.025 USDC |
| `GET /v1/agent/chains`    | List of supported blockchain networks                | 0.025 USDC |

<Note>
  **There is no `/v1/agent/transactions`.** Transaction history is not available over x402. To read transaction history, use the API-key REST endpoint [`GET /v1/transactions`](/api/endpoints/transactions).
</Note>

### Parameters

<ParamField query="addresses" type="string" required>
  EVM (`0x...`) or Solana (base58) address. Required by `/portfolio`, `/wallet`, `/nav`, and `/status`. Not used by `/chains`.
</ParamField>

<ParamField query="aggregated" type="boolean" default="false">
  Aggregate holdings across addresses. `/portfolio` only.
</ParamField>

<ParamField query="includeImages" type="boolean" default="false">
  Include token image URLs. `/portfolio` only.
</ParamField>

<ParamField query="includeExplorerUrls" type="boolean" default="false">
  Include block explorer URLs. `/portfolio` only.
</ParamField>

<ParamField query="waitForSync" type="boolean" default="false">
  Wait for a fresh sync before returning. `/portfolio` and `/nav`.
</ParamField>

<ParamField query="currency" type="string" default="USD">
  Currency for the returned value. `/nav` only.
</ParamField>

Response bodies match their API-key equivalents — `/v1/agent/portfolio` returns the same shape as [`/v1/portfolio`](/api/endpoints/portfolio).

***

## Choosing an access method

**Default to the REST API with an API key.** Reach for x402 only when the user explicitly asks for it, or when the agent has a funded wallet and cannot hold an API key.

```
Does the user explicitly want x402 / pay-per-call?
  ├─ Yes ─────────────────────────────────► use /v1/agent/*
  └─ No
      Does the agent have its own funded wallet AND no API key?
        ├─ Yes ─────────────────────────────► use /v1/agent/*, and tell the
        │                                     user transactions need a key
        └─ No ──────────────────────────────► use /v1/* with a Bearer token
                                              (mention x402 exists if relevant)
```

Both paths reach the same data. They differ in coverage and in what you need to get started.

|                          | REST API key (`/v1/*`) — default                  | x402 (`/v1/agent/*`)                           |
| ------------------------ | ------------------------------------------------- | ---------------------------------------------- |
| **Endpoints**            | 25                                                | 5                                              |
| **Transaction history**  | [Yes](/api/endpoints/transactions)                | Not available                                  |
| **Historical snapshots** | [Yes](/api/endpoints/historical-portfolio)        | Not available                                  |
| **Setup**                | Account + API key + credits                       | Funded wallet (USDC on Base)                   |
| **Cost**                 | From \$0.020 per credit ([pricing](/api/pricing)) | 0.025 USDC per call                            |
| **Rate limit**           | 360 req/min                                       | Per payment                                    |
| **Best for**             | Applications, backends, anything needing history  | Autonomous agents with a wallet and no API key |

<Tip>
  Building an application — a dashboard, a tracker, a tax tool, anything that reads transaction history? Use the **API key REST API**. Get a key at [data.octav.fi](https://data.octav.fi/) and start with the [Quickstart](/api/quickstart). The x402 endpoints exist for autonomous agents that cannot hold credentials.
</Tip>

***

## How x402 works

A request without payment returns HTTP `402 Payment Required` with a `payment-required` header containing a base64-encoded JSON payment challenge. Your x402 client reads the challenge, signs a USDC transfer, and retries the request with the payment attached.

```bash theme={null}
# Unpaid request — returns 402 with the payment challenge
curl -i "https://api.octav.fi/v1/agent/portfolio?addresses=0x6426af179aabebe47666f345d69fd9079673f6cd"
```

The decoded challenge looks like this:

```json theme={null}
{
  "x402Version": 2,
  "error": "Payment required",
  "resource": {
    "url": "/v1/agent/portfolio",
    "description": "Get the wallet and protocol holdings of a given address",
    "mimeType": "application/json"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "amount": "25000",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0x35BDDe2E5F25418c4a630751603c991138Af5253",
      "maxTimeoutSeconds": 300,
      "extra": { "name": "USD Coin", "version": "2" }
    }
  ]
}
```

`amount` is in USDC base units — `25000` = 0.025 USDC. `asset` is USDC on Base.

***

## Example Request

<CodeGroup>
  ```bash CLI theme={null}
  # The Octav CLI handles the x402 payment flow for you
  octav agent portfolio --addresses 0x6426af179aabebe47666f345d69fd9079673f6cd
  octav agent wallet --addresses 0x6426af179aabebe47666f345d69fd9079673f6cd
  ```

  ```javascript JavaScript theme={null}
  import { wrapFetchWithPayment } from 'x402-fetch';
  import { privateKeyToAccount } from 'viem/accounts';

  const account = privateKeyToAccount(process.env.AGENT_PRIVATE_KEY);
  const fetchWithPayment = wrapFetchWithPayment(fetch, account);

  // The wrapper catches the 402, pays, and retries automatically
  const response = await fetchWithPayment(
    'https://api.octav.fi/v1/agent/portfolio?addresses=0x6426af179aabebe47666f345d69fd9079673f6cd'
  );

  const portfolio = await response.json();
  console.log('Net worth:', portfolio[0].networth);
  ```

  ```python Python theme={null}
  import requests, base64, json

  url = 'https://api.octav.fi/v1/agent/portfolio'
  params = {'addresses': '0x6426af179aabebe47666f345d69fd9079673f6cd'}

  response = requests.get(url, params=params)

  if response.status_code == 402:
      challenge = json.loads(base64.b64decode(response.headers['payment-required']))
      print('Pay', int(challenge['accepts'][0]['amount']) / 1e6, 'USDC on Base')
      # Sign the payment with your x402 client, then retry with the payment header attached
  ```
</CodeGroup>

***

## Error Responses

<AccordionGroup>
  <Accordion title="402 Payment Required" icon="credit-card">
    Expected on every unpaid request — this is the x402 handshake, not a failure. Read the `payment-required` header, settle the payment, and retry.
  </Accordion>

  <Accordion title="404 Not Found" icon="circle-question">
    The `/v1/agent/*` path does not exist. Only `portfolio`, `wallet`, `nav`, `status`, and `chains` are exposed over x402.

    **Solution:** If you need transactions, historical data, approvals, or token overview, use the [API-key REST endpoints](/api/introduction) instead.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="All REST Endpoints" icon="code" href="/api/introduction">
    The full 25-endpoint API reference
  </Card>

  <Card title="Transactions" icon="receipt" href="/api/endpoints/transactions">
    Transaction history — API key only
  </Card>

  <Card title="CLI" icon="terminal" href="/api/ai-development/cli">
    `octav agent` commands with x402 built in
  </Card>

  <Card title="MCP Server" icon="plug" href="/api/ai-development/mcp-server">
    `octav_agent_portfolio` and `octav_agent_wallet` tools
  </Card>
</CardGroup>