Agent Endpoints (x402)

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

x402 is not the default way to use Octav — the REST API 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, Historical Portfolio, Token Overview, and Token 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.

Cost: 0.025 USDC per call, settled on Base (eip155:8453). No credits, no account.

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

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.

Parameters

string

required

EVM (0x...) or Solana (base58) address. Required by /portfolio, /wallet, /nav, and /status. Not used by /chains.

boolean

default:"false"

Aggregate holdings across addresses. /portfolio only.

boolean

default:"false"

Include token image URLs. /portfolio only.

boolean

default:"false"

Include block explorer URLs. /portfolio only.

boolean

default:"false"

Wait for a fresh sync before returning. /portfolio and /nav.

string

default:"USD"

Currency for the returned value. /nav only.

Response bodies match their API-key equivalents — /v1/agent/portfolio returns the same shape as /v1/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	Not available
Historical snapshots	Yes	Not available
Setup	Account + API key + credits	Funded wallet (USDC on Base)
Cost	From $0.020 per credit (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

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 and start with the Quickstart. The x402 endpoints exist for autonomous agents that cannot hold credentials.

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.

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

{
  "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

# The Octav CLI handles the x402 payment flow for you
octav agent portfolio --addresses 0x6426af179aabebe47666f345d69fd9079673f6cd
octav agent wallet --addresses 0x6426af179aabebe47666f345d69fd9079673f6cd

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);

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

Error Responses

402 Payment Required

Expected on every unpaid request — this is the x402 handshake, not a failure. Read the payment-required header, settle the payment, and retry.

404 Not Found

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

All REST Endpoints

The full 25-endpoint API reference

Transactions

Transaction history — API key only

CLI

octav agent commands with x402 built in

MCP Server

octav_agent_portfolio and octav_agent_wallet tools

Getting Started

Endpoints

Playground

AI Development

Migrate to Octav

Reference

Available x402 endpoints

Parameters

Choosing an access method

How x402 works

Example Request

Error Responses

All REST Endpoints

Transactions

CLI

MCP Server

​Available x402 endpoints

​Parameters

​Choosing an access method

​How x402 works

​Example Request

​Error Responses

​Related

All REST Endpoints

Transactions

CLI

MCP Server

Available x402 endpoints

Parameters

Choosing an access method

How x402 works

Example Request

Error Responses

Related