0 active

DOCS / QUICKSTART

Quickstart

Install the SDK, define a spend grant, make a paid call. About twenty lines, no API keys to the services you call — payment is USDC on Base via the x402 protocol.

1. Install

npm install yeetful viem

viem is a peer dependency, so the SDK stays light and tracks whatever viem version your app already uses.

2. A wallet

Any viem WalletClientworks — a small dedicated burner for development, or a Coinbase Developer Platform wallet in production (CDP accounts satisfy viem's account interface, so they drop straight in). Fund it with a few dollars of USDC on Base; payments are gasless EIP-3009 authorizations, so no ETH is needed.

import { createWalletClient, http } from 'viem'
import { base } from 'viem/chains'
import { privateKeyToAccount } from 'viem/accounts'

const wallet = createWalletClient({
  account: privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`),
  chain: base,
  transport: http(),
})

3. The expense account

import { yeetful, GrantError } from 'yeetful/agent'

const pay = yeetful({
  wallet,
  grant: {
    allow: ['tripadvisor.x402.paysponge.com', 'anthropic.yeetful.com'],
    perCallUsd: 0.05, // refuse any single call above 5¢
    perDayUsd: 2,     // refuse once today's spend would pass $2
    expiresAt: '2026-12-31',
  },
  onReceipt: (r) => console.log(r.host, `$${r.amountUsd}`, r.txHash ?? r.note),
})

4. Pay per call

try {
  const res = await pay('https://tripadvisor.x402.paysponge.com/api/v1/location/search?searchQuery=tokyo')
  console.log(await res.json())
  console.log(`spent today: $${pay.spentTodayUsd()} / left: $${pay.remainingTodayUsd()}`)
} catch (e) {
  // GrantError.code: NOT_ALLOWED | OVER_PER_CALL | BUDGET_EXCEEDED | EXPIRED | REVOKED
  if (e instanceof GrantError) console.error(`blocked: ${e.code}`)
}

pay() behaves like fetch: non-402 responses pass straight through (still allowlist-checked and receipted at $0), and a 402 challenge triggers the grant check → sign → retry flow automatically. Off-policy calls throw before any network or payment activity.

Next