Quickstart

This walks through the shortest path from a running gateway to a paid, metered call: register an agent, proxy a call through it, then price it and gate the call behind an x402 payment.

Start the gateway first — see Install. Everything below assumes make dev-auth is running and TOKEN holds the bearer token it wrote to /tmp/farcaster-dev-token:

TOKEN=$(cat /tmp/farcaster-dev-token)

1. Register your first agent

An agent is a catalog entry: a name and an upstream_url Farcaster will proxy calls to.

curl -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
     -d '{"name":"support-bot","description":"handles refunds","upstream_url":"https://your-upstream.example.com"}' \
     localhost:8080/v1/agents

The response includes the agent’s id — use it below.

2. Proxy a call through it

curl -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
     -d '{}' \
     localhost:8080/v1/proxy/{id}

Farcaster forwards the call to upstream_url, records the invocation (latency, status, body if capture is enabled), and returns the upstream’s response. POST /v1/proxy/{id}/stream does the same for streaming calls; GET /v1/invocations lists what was captured.

3. Gate a paid tool

Set a price on the agent to require a stablecoin payment before Farcaster will proxy a call to it. Pricing is USDC on Base:

curl -X PATCH -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
     -d '{"price":{"amount":"10000","asset":"USDC","network":"base","pay_to":"0xYourPayoutAddress"}}' \
     localhost:8080/v1/agents/{id}

Now a call without a payment is held at the gate:

curl -i -H "Authorization: Bearer $TOKEN" -X POST localhost:8080/v1/proxy/{id}
# HTTP/1.1 402 Payment Required
# {"x402Version":1,"accepts":[{"scheme":"exact","network":"base","asset":"...","payTo":"0xYourPayoutAddress", ...}]}

A caller that presents a valid, signed x402 payment authorization in the X-PAYMENT header — one satisfying the accepts terms in the 402 body — is verified and forwarded normally. Farcaster never holds the caller’s or the operator’s private key; it only verifies the signed authorization. See Sovereignty & no-custody for why that matters, and OSS vs Commercial at a glance for what happens after verification (collecting the payment on-chain is a managed-tier capability).