Recall & x402

What is x402?

x402 is an open standard that uses the long-dormant HTTP status code 402 Payment Required to negotiate per-call micropayments. A server announces what it costs to access a resource; the client returns a signed payment authorization; both are settled on-chain in the same request.

For Pinecode, x402 means an agent can query memory without an API key, without an account, without a subscription. The agent's wallet is its identity and its payment method, in one.

The recall flow

Agent                Gateway               Indexer            Settlement
  │                     │                     │                    │
  ├── POST /recall ────▶│                     │                    │
  │◀── 402 + challenge ─┤                     │                    │
  │                     │                     │                    │
  ├── sign EIP-712 ─────│                     │                    │
  ├── POST + x-payment ▶│                     │                    │
  │                     ├── HNSW query ──────▶│                    │
  │                     │◀── ranked seeds ──┤                    │
  │                     ├─── settle payment ────────────────────▶  │
  │                     │                     │                    │
  │◀── 200 + results ───┤                     │                    │

Pricing

The fee for a recall is the sum of:

• A base gateway fee (currently $0.0005)
• A per-hit fee proportional to each returned seed's quality score
• Optional priority routing fee (skip queues, use the lowest-latency indexer)

Typical recall costs $0.001 – $0.01 USDC. Cap it per-call with paymentMax.

Pre-funded balances

For agents making many calls per second, single-call settlement adds latency. The gateway supports pre-funded balances:

class=class="text-success/90">"text-fg-subtle italic">// Deposit USDC into your account's balance
await pinecode.balance.deposit({ amount: class="text-success/90">"50" }); class=class="text-success/90">"text-fg-subtle italic">// USDC
class=class="text-success/90">"text-fg-subtle italic">// Subsequent recalls debit from balance instead of x402
const hits = await pinecode.recall({ query: class="text-success/90">"..." });
class=class="text-success/90">"text-fg-subtle italic">// Check remaining
const { balance } = await pinecode.balance.get();

Settlement guarantees

• Payments are final on Base block 1 (~1 second)
• If the gateway returns 5xx after taking payment, the SDK auto-refunds via signed dispute
• Failed payments are reverted via the PinecodePayments escrow contract
• Settled receipts are queryable via GET /receipts/:id