Buy API access

What this is

API access is metered per call in GRID (1 GRID = 0.01 USDC of service).

• A free key (POST /v1/register) keeps its free allowance every day.
• A key with a balance runs at ten times the rate. Each call past the free allowance is debited at the list price:

Read the live numbers from GET /v1/access; never copy them from here.

There is no subscription. You send USDC on Base from your own wallet to the payee, sign one message with that wallet, and the key is credited: 100 GRID per 1 USDC, from 1 to 20 USDC per transaction.

Before you start

• A key: POST /v1/register (no body) answers api_key once.
• For the top-up itself: a wallet (an EOA) holding USDC and a little ETH on Base. The commands below never sign or send.

export TAIFOON=https://coord.taifoon.dev/v1
tf() { curl -sS -m 60 -H "X-Taifoon-Client: taifoon-skill-buy-access" -H "content-type: application/json" ${TAIFOON_API_KEY:+-H "X-API-Key: $TAIFOON_API_KEY"} "$@"; }

Pitfalls

1. Sending an amount that was not quoted. Only an exact whole number of USDC from 1 to 20, sent by the wallet that signs, to the payee in the quote, counts. 1.5 USDC is refused and nothing is credited.
2. Signing with another wallet. The message names your key, and only the wallet that sent the transfer may sign it.
3. Sending the transfer from a contract wallet. The top-up reads the transaction's sender; send it from an EOA.
4. Topping up a key, then rolling it. The balance stays with the key it was credited to. Spend it, or keep the key.
5. Retrying a top-up and fearing a double credit. A transaction credits once. The same key sending it again gets already: true. Another key gets 409.
6. Reading a 402 as an outage. code: budget means the key's own cap (reason: cap_day | cap_month) or its balance (reason: balance). next_step and top_up say what lifts it.

Steps

1. The products and prices

tf "$TAIFOON/access" | jq -e '.schema == "taifoon.access.v1" and (.products | length) == 6 and ([.products[].price.per_1000_grid] | all(. > 0)) and (.checkout.payee | test("^0x[0-9a-fA-F]{40}$"))' >/dev/null

2. Your key's standing

if [ -n "${TAIFOON_API_KEY:-}" ]; then
  tf "$TAIFOON/access/key" | jq -e '.ok and (.tier == "free" or .tier == "paid") and (.permissions.scopes | length) > 0 and has("balance")' >/dev/null
fi

3. The quote for 1 USDC

Q=$(tf "$TAIFOON/access/quote?usdc=1")
echo "$Q" | jq -e '.ok and .pay.chainId == 8453 and .pay.amount == "1.000000" and .credits.grid == 100 and (.pay.call.data | startswith("0xa9059cbb"))' >/dev/null

With a key, sign.message is the exact text to sign. Without one it is null, and the steps say to get a key first.

4. Pay and sign (your wallet, not this script)

1. Send pay.call (to, data, value: 0x0) on Base from your wallet.
2. Take the transaction hash.
3. Sign sign.message with the hash filled in, using personal_sign from the same wallet.

cast send <pay.call.to> <pay.call.data> --rpc-url https://mainnet.base.org --private-key …   # or any wallet
cast wallet sign "<sign.message with the tx hash>"                                          # the same wallet

5. Credit the key

if [ -n "${TX:-}" ] && [ -n "${SIG:-}" ]; then
  tf -X POST "$TAIFOON/access/topup" -d "{\"tx\":\"$TX\",\"signature\":\"$SIG\"}" | jq -e '.ok and (.balance.grid > 0)' >/dev/null
fi

6. Cap and scope a key

One more key, labelled, for a bot that may only read chains and prove, spending at most 50 GRID a day:

POST /v1/tenant/keys { "action": "create", "label": "indexer", "scopes": ["rpc", "proofs"], "cap_day_grid": 50, "cap_month_grid": 1000 }
POST /v1/tenant/keys { "action": "update", "prefix": "tfr_free_…", "origins": ["https://app.example.com"] }   # null clears a field

Verify it works

if [ -n "${TAIFOON_API_KEY:-}" ]; then
  tf "$TAIFOON/access/usage?window=7d" | jq -e '.ok and (.families | has("rpc") and has("proofs") and has("events")) and (.total.calls >= 0)' >/dev/null
fi
echo "buy-access: price list, quote and standing read"

What it costs

The top-up is the USDC you send plus Base gas. 1 USDC credits 100 GRID, spent per call only past the free allowance. Reading the quote, the standing and the usage costs nothing.

Next

• Spend it on chain reads: rent-rpc. On proofs: prove-anything.
• Give the key to an agent: wrap-in-an-agent.