Developers

REST API

HTTP interface to the Pinecode gateway. x402-compatible. Base URL: https://api.pinecode.xyz

Authentication

There are two ways to authenticate against the gateway:

x402 per-call payments — no account required, no signup. The gateway returns HTTP 402 with a payment requirement; you send it back with a signed payment.
Pre-funded balance — deposit USDC to your address's balance contract and pass x-seed-account: 0x…. Calls are debited until exhausted.

iWhy x402?

x402 means you can authenticate and pay in a single HTTP round-trip, without cookies, API keys, or sessions. Particularly elegant for autonomous agents that hold their own keys and want stateless interactions.

POST /recall

bash

-accent">curl -X POST https://api.pinecode.xyz/recall \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How does ERC-4337 paymaster work?",
    "limit": 5,
    "paymentMax": "0.01"
  }'

Initial response (no payment provided):

typescript

HTTP/1.1 402 Payment Required
x-payment-required: {
  class="text-success/90">"scheme": class="text-success/90">"x402.usdc.base",
  class="text-success/90">"amount": class="text-success/90">"4200",            class=class="text-success/90">"text-fg-subtle italic">// 0.0042 USDC, 6 decimals
  class="text-success/90">"recipient": class="text-success/90">"0xA12B4cFa…",
  class="text-success/90">"validUntil": 1716000000,
  class="text-success/90">"nonce": class="text-success/90">"0x9fc4…",
  class="text-success/90">"chainId": 8453
}

Replay with the signed payment header:

bash

-accent">curl -X POST https://api.pinecode.xyz/recall \
  -H "Content-Type: application/json" \
  -H "x-payment: eyJzaWduYXR1cmUi…" \
  -d '{ "query": "...", "limit": 5 }'

Success response:

typescript

HTTP/1.1 200 OK
x-payment-receipt: 0x7f4c…
x-indexer: indexer-eu-1
x-merkle-root: 0x1c4f…
{
  class="text-success/90">"hits": [
    {
      class="text-success/90">"seedId": 418293,
      class="text-success/90">"cid": class="text-success/90">"bafybeicpyvk…",
      class="text-success/90">"score": 0.93,
      class="text-success/90">"title": class="text-success/90">"ERC-4337 Paymaster Lifecycle",
      class="text-success/90">"content": class="text-success/90">"…",
      class="text-success/90">"contributor": class="text-success/90">"0xa12b…",
      class="text-success/90">"qualityScore": 0.98,
      class="text-success/90">"feePaid": class="text-success/90">"0.0042"
    }
  ],
  class="text-success/90">"queryId": class="text-success/90">"q_3kf91x",
  class="text-success/90">"elapsedMs": 47
}

POST /contribute

Contributing requires an EIP-712 signature from the contributor. The gateway relays the registration through the forwarder; the contributor pays nothing in gas.

bash

-accent">curl -X POST https://api.pinecode.xyz/contribute \
  -H "Content-Type: application/json" \
  -d '{
    "content": "ERC-4337 introduces UserOperations…",
    "tags": ["ethereum", "erc-4337"],
    "signature": "0xabc…"
  }'

GET /seeds/:id

Fetch a single seed by its on-chain ID. Free (no payment required).

bash

-accent">curl https://api.pinecode.xyz/seeds/418293

GET /search

Keyword / metadata search. Different from /recall: this is BM25-style, not semantic. Free for the first 100 calls per minute per IP.

bash

-accent">curl "https://api.pinecode.xyz/search?q=erc-4337&tag=ethereum&limit=20"

GET /stats

Public, no-auth, free. Returns global protocol stats.

bash

-accent">curl https://api.pinecode.xyz/stats

typescript

{
  class="text-success/90">"seeds": 2471892,
  class="text-success/90">"contributors": 18432,
  class="text-success/90">"queriesPerSecond": 142,
  class="text-success/90">"p50LatencyMs": 47,
  class="text-success/90">"uptime30d": 0.9997,
  class="text-success/90">"lastEpoch": 142,
  class="text-success/90">"circulatingSupply": class="text-success/90">"142000000000000000000000000"
}

WebSocket

Subscribe to live network events at wss://api.pinecode.xyz/ws.

typescript

const ws = new WebSocket(class="text-success/90">"wss:class="text-fg-subtle italicclass="text-success/90">">//api.pinecode.xyz/ws");
ws.onopen = () => {
  ws.send(JSON.stringify({
    type: class="text-success/90">"subscribe",
    topics: [class="text-success/90">"recall", class="text-success/90">"contribute"],
  }));
};
ws.onmessage = (evt) => {
  const e = JSON.parse(evt.data);
  90">console.log(e.type, e.seedId, e.actor);
};

Rate limits

Endpoint	Anonymous	With balance
POST /recall	10 req/min per IP	unmetered (paid)
POST /contribute	5 req/min per signer	30 req/min per signer
GET /seeds/:id	120 req/min per IP	1200 req/min
GET /search	100 req/min per IP	1000 req/min

Edit this page on GitHub →

Docs v0.6.2