Build a Bippsi-aware agent in 20 lines

Prerequisites

1. Mint an agent key at bippsi.com/agent-initiative/key. Takes 30 seconds. Set it as BIPPSI_AGENT_KEY in your environment.
2. Top up a small Bip balance at bippsi.com/ai-key. 25 Bips ≈ $0.025. You'll spend pennies running this.
3. Install the SDK: Python or Node. Alpha is install-from-source; npm + PyPI pending.

Python — 19 lines

import os, sys
from bippsi import BippsiClient, OverspendCapError

query    = sys.argv[1] if len(sys.argv) > 1 else 'quantum computing'
budget   = int(os.environ.get('BATCH_BUDGET', 50))
per_call = 25

bippsi = BippsiClient(max_price_per_request=per_call)
r = bippsi.discover(q=query, access='paid', limit=10)

spent = 0
for row in r['results']:
    if row['access']['price_bips'] > budget - spent: continue
    try:
        res = bippsi.fetch(row['resource_url'])
        spent += res['paid']
        print(f"[{row['partner']}] {row['title']}")
        print(f"  {res['body'][:200] if isinstance(res['body'], str) else str(res['body'])[:200]}…\n")
    except OverspendCapError: pass

print(f"--- spent {spent} Bips across {query!r}")

Run: python agent.py "ai model benchmarks"

Node — 19 lines

import { BippsiClient, OverspendCapError } from '@bippsi/client';

const query    = process.argv[2] || 'quantum computing';
const budget   = Number(process.env.BATCH_BUDGET || 50);
const perCall  = 25;

const bippsi = new BippsiClient({ maxPricePerRequest: perCall });
const r = await bippsi.discover({ q: query, access: 'paid', limit: 10 });

let spent = 0;
for (const row of r.results) {
  if (row.access.price_bips > budget - spent) continue;
  try {
    const res = await bippsi.fetch(row.resource_url);
    spent += res.paid;
    const excerpt = typeof res.body === 'string' ? res.body.slice(0, 200) : JSON.stringify(res.body).slice(0, 200);
    console.log(`[${row.partner}] ${row.title}`);
    console.log(`  ${excerpt}…\n`);
  } catch (err) { if (!(err instanceof OverspendCapError)) throw err; }
}
console.log(`--- spent ${spent} Bips across "${query}"`);

Run: node agent.mjs "ai model benchmarks"

What it does, step by step

1. Discover. bippsi.discover({ q, access: 'paid' }) hits /registry/search — a cross-site search over every certified Partner that opted resources into the registry. No auth, no Partner-by-Partner probing.
2. Budget-cap per call. Each resource arrives with a price_bips in its access block. We skip anything that would bust the batch budget BEFORE trying to fetch it. Zero wasted 402 round-trips.
3. Fetch with auto-retry. bippsi.fetch(url) does the first request with no auth. If the server returns 402, the SDK reads the price from the 402 body, verifies it's within the cap, adds Authorization: Bearer bak_* + Payment: bips N headers, and retries. On 2xx it returns the paid body.
4. Per-call cap is a hard stop. If a URL prices above per_call, the SDK throws OverspendCapError instead of paying. Good hygiene — a pricing bug on a Partner's side can't drain your wallet.
5. Read what you fetched. Because the content is now in res.body, the agent can quote from it instead of hallucinating. Cite the row.partner + URL and you're done.

Where to go next

• Protocol overview — how 402 retry works at the wire level →
• Deep training — comprehensive fallback doc for agent builders →
• Agent workbook — decision trees + self-tests + downloadable training corpus →
• Node SDK reference →
• Python SDK reference →
• Browse the registry (human-friendly) →