Skip to main content

Using the API

Once connected to the AntSeed network, your buyer proxy exposes a local API at http://localhost:8377. Point any AI tool at this endpoint — the proxy handles peer discovery, routing, and payments transparently.

Quick Start​

# 1. Install
npm install -g @antseed/cli

# 2. Set your identity
export ANTSEED_IDENTITY_HEX=<your-private-key-hex>

# 3. Start the buyer proxy
antseed buyer start
# Proxy listening on http://localhost:8377

# 4. Pick a peer to route through
antseed network browse                              # list peers + services
antseed buyer connection set --peer <40-char-hex>   # pin one

# 5. Deposit USDC when you want to pay providers
antseed payments
# Open http://localhost:3118, connect a funded wallet, deposit USDC

Until a peer is pinned, every request returns no_peer_pinned — there is no auto-selection. See Pick a peer below.

antseed buyer start does not require a pre-existing ~/.antseed/config.json. If the file is missing, the CLI starts with built-in defaults such as router local and proxy port 8377.

Buyer state isolation​

Buyer runtime state is stored in the CLI data directory. By default this is ~/.antseed, where the proxy writes buyer.state.json, SQLite databases, payment-channel files, and the fallback identity.key.

For multiple buyer nodes, service integrations, isolated tests, or concurrent processes, give each buyer its own data directory:

export BUYDIR="$HOME/.antseed-buyer-myapp"
mkdir -p "$BUYDIR"

ANTSEED_DATA_DIR="$BUYDIR" \
antseed --data-dir "$BUYDIR" buyer start \
  --peer <peer-id> \
  --port 8380

Use --data-dir <path> in service/systemd scripts because it is explicit. ANTSEED_DATA_DIR=<path> is useful for wrappers and local scripts. Do not reuse the same buyer data directory across concurrent processes.

If the buyer proxy starts but appears to use stale pins, waits on broad discovery, times out before payment negotiation, or shows sessions/channels in an unexpected place, check the startup log for the resolved data directory and buyer.state.json path. ANTSEED_HOME is not the CLI state-isolation setting; use --data-dir or ANTSEED_DATA_DIR.

Extra buyer config is optional. Add it only for advanced customization such as pricing caps, reputation thresholds, bootstrap nodes, or chain settings:

{
  "buyer": {
    "minPeerReputation": 0,
    "maxPricing": {
      "defaults": {
        "inputUsdPerMillion": 25,
        "outputUsdPerMillion": 75
      }
    }
  },
  "payments": {
    "preferredMethod": "crypto",
    "crypto": {
      "chainId": "base-mainnet"
    }
  }
}

With a config file like that in place, the startup command is still just:

antseed buyer start

Supported API Formats​

The proxy accepts three API formats. Use whichever matches your tool:

EndpointFormatCompatible Tools
/v1/messagesAnthropic Messages APIClaude Code, Claude SDK
/v1/chat/completionsOpenAI Chat CompletionsCodex, any OpenAI-compatible client
/v1/responsesOpenAI Responses APICodex

The model field in your request determines which service to route to. The proxy finds the best available provider for that service on the network.

Claude Code​

export ANTHROPIC_BASE_URL=http://localhost:8377
claude

Claude Code sends requests to /v1/messages and the proxy routes them to the best available Anthropic provider on the network.

Codex​

Recent Codex versions (0.40+) ignore OPENAI_BASE_URL and OPENAI_API_KEY and only read ~/.codex/config.toml. See the Codex integration page for the profile-based setup, the routing-verification check, and known gotchas (project-local configs, -c flag pitfalls).

curl​

# Anthropic format
curl http://localhost:8377/v1/messages \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

# OpenAI format
curl http://localhost:8377/v1/chat/completions \
  -H "content-type: application/json" \
  -d '{
    "model": "deepseek-v3.1",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Pick a peer​

The buyer proxy does not auto-select peers. Every request returns no_peer_pinned until you pin one — this keeps routing predictable and puts pricing/quality choice in your hands.

# List peers and the services each one offers
antseed network browse

# Inspect one peer in detail (pricing, protocols, on-chain stats)
antseed network peer <40-char-hex-peer-id>

# Pin a peer for the session (survives daemon restart)
antseed buyer connection set --peer <40-char-hex-peer-id>

# Pin a service too — overrides the `model` field in all requests
antseed buyer connection set --service claude-opus-4-6

# Clear pins
antseed buyer connection clear

You can also pin per-request by sending the x-antseed-pin-peer: <peerId> header — useful when different calls should go to different peers.

How Routing Works​

When you send a request:

  1. The proxy verifies a peer is pinned; if not, it returns no_peer_pinned.
  2. It checks the pinned peer's metadata for the requested model (the service name).
  3. The request is forwarded to that peer via encrypted WebRTC.
  4. The response streams back through the proxy.

No API Key Needed​

The proxy does not require an API key. Authentication and payments are handled by the protocol using your node's identity key and on-chain USDC deposits. Tools that require an API key (like Codex) can use any placeholder value.

Monitor Buyer Usage​

Expose buyer metrics with:

antseed metrics serve --role buyer

See Metrics for buyer spend, channel, request, token, and per-peer metrics.

Agent Skills​

If you're using Pi, Codex or another agent, these skills can walk you through the full setup: