yeetful

yeetful

Spend-controlled x402 for AI agents. Give an agent an expense account — an allowlist of endpoints plus per-call / per-day budgets — and let it pay any x402 service with no API keys. Enforcement is local and instant; every call emits a receipt. Built for Yeetful, MIT-licensed, works anywhere TypeScript does.

npm install yeetful viem

Agent expense account

Wrap your agent's calls in one grant-aware pay(). It refuses anything off the allowlist or over budget before signing a payment — your guardrail against runaway loops, bugs, and prompt-injected tool calls.

import { yeetful, GrantError } from 'yeetful/agent'
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(),
})

const pay = yeetful({
  wallet,
  grant: {
    allow: ['tripadvisor.x402.paysponge.com', 'anthropic.yeetful.com'],
    perCallUsd: 0.05,
    perDayUsd: 2,
    expiresAt: '2026-12-31',
  },
  onReceipt: (r) => console.log(r.host, `$${r.amountUsd}`, r.txHash ?? r.note),
})

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
  //   | OVER_AGENT_BUDGET | OVER_ORG_BUDGET | AGENT_PAUSED | ACCOUNT_FROZEN
  if (e instanceof GrantError) console.error(`blocked: ${e.code}`)
}

One grant authorizes many endpoints (the allowlist). Use onReceipt to stream the audit trail to your dashboard or the Yeetful control plane.

Hosted-ledger sync

Mirror a grant you created at yeetful.com and pass an API key (minted on the dashboard) — every receipt then syncs to your hosted ledger, so budgets and the audit feed include this agent's calls:

const pay = yeetful({
  wallet,
  grant: { id: 'your-grant-id', allow: [...], perCallUsd: 0.05, perDayUsd: 2 },
  apiKey: process.env.YEETFUL_API_KEY, // yf_…
})
// …
await pay.flushLedger() // before a short-lived script exits

Sync is best-effort and never blocks or fails a payment; denials are synced too (ok: false with the violation code).

ledgerUrl must be the canonical origin (currently https://www.yeetful.com): fetch silently drops the Authorization header when it follows a cross-origin redirect such as apex → www. If sync or the policy fetch fails after a redirect, the onEvent log names the origin to use.

Per-key agent budgets

On yeetful.com an agent is an API key — the dashboard's Agents tab gives each key a per-day USD budget and a spent-today meter. When you pass apiKey, the SDK fetches the key's policy (GET /api/agent/policy) before the first payment and refuses to pay once the key is over budget, or when a call's quoted price would exceed what's left today:

const pay = yeetful({ wallet, grant: { id: 'your-grant-id', ... }, apiKey: process.env.YEETFUL_API_KEY })

console.log(pay.agentBudget()) // { keyId, label, perDayUsd, spentTodayUsd, remainingTodayUsd, overBudget }
// over budget → pay() throws GrantError('OVER_AGENT_BUDGET') and syncs the
// denial receipt, so the refusal shows up in the dashboard audit trail.

Budgets are advisory at the rails — the agent pays from its own wallet, so this local refusal is the enforcement point. The snapshot stays fresh opportunistically: receipt-sync responses echo the updated budget, flushLedger() re-fetches the policy (picking up mid-run dashboard edits), and settled-but-unsynced spend is counted locally in between. If the policy can't be fetched at all, payments proceed under the grant alone.

Local vs. hard enforcement. This SDK enforces the grant in-process — ideal for governing your own agents (runaway loops, bugs, injected tool calls). For adversarial guarantees, back the grant with an on-chain Coinbase Spend Permission so the wallet contract caps spend regardless of the SDK.

Org budgets & remote pause (0.5)

If the key belongs to an organization on yeetful.com, the same apiKey flow adds two more controls — fetched from the policy, refreshed on every sync echo, and enforced locally just like the per-key budget:

• Two-level budget. The org has a daily USD cap above each key's own budget — summed across all the org's agents. A call that would breach it throws GrantError('OVER_ORG_BUDGET'). Over either level stops the payment.
• Remote kill switch. An admin can freeze a single agent (AGENT_PAUSED) or the whole expense account (ACCOUNT_FROZEN) from the dashboard. The SDK halts all payments while frozen — a hard stop above any budget arithmetic — and resumes automatically on the next policy refresh once unfrozen.

const pay = yeetful({ wallet, grant: { id: 'your-org-grant-id', ... }, apiKey: process.env.YEETFUL_API_KEY })

pay.orgBudget() // { id, name, perDayUsd, spentTodayUsd, overBudget } | null (null for personal keys)
pay.status()    // { halted, haltReason: 'AGENT_PAUSED' | 'ACCOUNT_FROZEN' | null }

// org over its cap   → GrantError('OVER_ORG_BUDGET')
// agent/account paused → GrantError('AGENT_PAUSED' | 'ACCOUNT_FROZEN'), before any network call

Same honesty as budgets: pause is advisory at the rails for SDK agents paying their own wallet (this local refusal is the enforcement); the chats Yeetful itself executes are hard-stopped server-side, and on-chain hard stops arrive with Spend Permissions.

---

Low-level x402 primitives

The agent wrapper is built on a full x402 toolkit you can use directly:

// Server — gate a route for 1¢ USDC
import { withPayment } from 'yeetful/next'

export const GET = withPayment(
  { price: '0.01', recipient: '0xYourAddress', network: 'base' },
  async () => Response.json({ secret: 'gm' })
)

// Client — auto-pay when a server returns 402 (no grant enforcement)
import { createPaymentClient } from 'yeetful/client'

const pay = createPaymentClient({ wallet })
const res = await pay('https://api.example.com/premium')
console.log(await res.json()) // → { secret: 'gm' }

---

Why x402?

x402 is a reborn HTTP 402 Payment Required — a protocol where servers quote a price, clients sign a stablecoin authorization, and a facilitator settles on-chain. No accounts, no Stripe dashboards, no webhook retries. Works on EVM chains today (USDC on Base, Optimism, Arbitrum, Polygon, Ethereum).

You get:

• Per-request pricing for any API — LLM calls, data feeds, premium endpoints, MCP tools.
• One-sentence paywalls for agents: an LLM with a wallet can now pay for what it uses.
• Instant settlement on L2 — no chargebacks, no holds, no 30-day payout delay.

---

Install

npm install yeetful viem
# or
pnpm add yeetful viem
# or
yarn add yeetful viem

viem is a peer dependency so the SDK stays light and stays in sync with whatever viem version your app already uses.

---

Quickstart

Server: gate a route

Next.js (App Router)

// app/api/premium/route.ts
import { withPayment } from 'yeetful/next'

export const GET = withPayment(
  {
    price: '0.01',                        // USD
    recipient: '0xYourWalletAddress',     // gets paid
    network: 'base',                      // or ['base', 'optimism']
    description: 'Premium GM endpoint',
  },
  async (req) => {
    return Response.json({ message: 'gm, thanks for the cent' })
  }
)

Express

import express from 'express'
import { paymentRequired } from 'yeetful/express'

const app = express()

app.get(
  '/premium',
  paymentRequired({
    price: '0.01',
    recipient: '0xYourWalletAddress',
    network: 'base',
  }),
  (req, res) => {
    res.json({ message: 'gm', payer: req.x402?.payer })
  }
)

app.listen(3000)

Anywhere else (Hono, Bun, Cloudflare Workers, raw Node)

Use the runtime-agnostic gate() helper. Give it a standard Request, get back either a 402 Response or a settle() handle.

import { gate } from 'yeetful/server'

export default {
  async fetch(request: Request) {
    const result = await gate(request, {
      price: '0.01',
      recipient: '0xYourWalletAddress',
      network: 'base',
    })

    if (result.type === 'paymentRequired') return result.response

    // …do the paid work…
    const body = Response.json({ message: 'gm' })

    const { header } = await result.settle()
    body.headers.set('X-PAYMENT-RESPONSE', header)
    return body
  },
}

Server: track earnings on your dashboard

Claimed your MCP on yeetful.com? Report each paid call so your earnings — total, last 30 days, calls served, paying agents — show up on your dashboard. reportUsage() is fire-and-forget: it never throws and never blocks, so call it after settle() and don't await it on the hot path (on serverless, hand it to ctx.waitUntil(...)).

import { gate, reportUsage } from 'yeetful/server'

const { payer, settle } = /* …from gate() … */
const { header, result } = await settle()

// non-blocking — do NOT await on the request's critical path
reportUsage({
  apiKey: process.env.YEETFUL_API_KEY!, // a yf_… key from dashboard/keys
  mcp: 'your-server-slug',              // your slug on yeetful.com/servers/<slug>
  amountUsd: 0.01,
  payer,
  tool: 'list_proposals',
  network: 'base',
})

Full walk-through: yeetful.com/docs/earn.

Client: auto-pay

import { createPaymentClient } from 'yeetful/client'

const pay = createPaymentClient({
  wallet,                           // any viem WalletClient
  maxAmountAtomic: 1_000_000n,      // cap: 1 USDC per call
  allowedNetworks: ['base'],        // only pay on Base
  onPaymentRequired: async (req) => {
    console.log(`Pay ${req.maxAmountRequired} to ${req.payTo}?`)
    return true                     // return false to cancel
  },
})

// Use exactly like fetch.
const res = await pay('https://api.example.com/premium')

---

Configuration

RouteGateOptions — server

Option	Type	Default	Notes
price	string | number	required	USD amount, e.g. '0.01'. Converted to USDC atomic units.
recipient	Address	required	Address that receives the payment.
network	X402Network | X402Network[]	'base'	Networks you'll accept. Multi-chain = multi-item discovery.
asset	Address	USDC for network	Override to use a different ERC-20.
description	string	—	Shown to the paying client.
maxTimeoutSeconds	number	600	Validity window of the signed authorization.
facilitator	FacilitatorConfig | false	hosted facilitator	Pass false to skip on-chain settlement (testing only).

Supported networks: base, base-sepolia, ethereum, optimism, arbitrum, polygon.

ClientOptions — client

Option	Type	Notes
wallet	WalletClient	Any viem wallet capable of signing EIP-712 typed data.
maxAmountAtomic	bigint	Reject requirements above this cap — safety belt.
allowedNetworks	X402Network[]	Only pay on these networks.
onPaymentRequired	(req) => boolean | Promise<boolean>	Approval hook; return false to cancel.
fetch	typeof fetch	Override the underlying fetch (e.g. for timeouts).

---

How it works

1. Client requests a paid resource normally.
2. Server responds with 402 Payment Required and a JSON body listing acceptable requirements (network, asset, amount, recipient).
3. Client picks the cheapest requirement, signs an EIP-3009 TransferWithAuthorization with the user's wallet, and retries the request with an X-PAYMENT header (base64 JSON).
4. Server hands the signed payload to a facilitator which verifys the signature and settles the transfer on-chain.
5. Server runs the handler and returns the response with an X-PAYMENT-RESPONSE header containing the transaction hash.

The signing is gasless for the payer — the facilitator broadcasts the transfer and picks up gas.

---

Facilitators

By default the SDK uses the hosted facilitator at https://facilitator.yeetful.com. Override it anywhere you configure the server:

withPayment(
  {
    price: '0.01',
    recipient: '0xYourAddress',
    facilitator: {
      url: 'https://your-facilitator.example.com',
      authHeader: 'Bearer your-token',
    },
  },
  handler,
)

Pass facilitator: false to skip verification and settlement entirely — only useful for local testing.

---

Advanced

Accept multiple networks

withPayment(
  {
    price: '0.01',
    recipient: '0xYourAddress',
    network: ['base', 'optimism', 'arbitrum'],
  },
  handler,
)

Clients automatically pick the cheapest network they're configured to use.

Sign a payment manually

import { signPayment } from 'yeetful/client'

const payment = await signPayment(wallet, {
  scheme: 'exact',
  network: 'base',
  asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', // USDC
  maxAmountRequired: '10000', // 0.01 USDC
  payTo: '0xRecipient',
})

Use with AI agents / MCP tools

x402 is a natural fit for agent tooling — drop withPayment in front of any MCP tool endpoint and agents with wallets can pay per-call. This SDK is what powers paid tools on Yeetful.

---

API reference

yeetful/server

• gate(request, options) — runtime-agnostic. Returns { type: 'paymentRequired', response } or { type: 'ok', payer, settle }.
• reportUsage(options) — fire-and-forget earn-side receipt to your Yeetful dashboard. Never throws; resolves true on a 2xx.
• Facilitator — thin wrapper around verify/settle HTTP endpoints.
• DEFAULT_FACILITATOR_URL — the hosted facilitator URL.
• DEFAULT_RECEIPTS_URL — the hosted earn-side ingestion URL.

yeetful/next

• withPayment(options, handler) — wraps a Next.js route handler.

yeetful/express

• paymentRequired(options) — returns an Express RequestHandler. Sets req.x402.payer after successful verification.

yeetful/client

• createPaymentClient(options) — returns a fetch-compatible function that handles 402s automatically.
• signPayment(wallet, requirement) — sign a payment payload by hand.
• PaymentError — thrown when the client declines to pay.

Helpers

• usdcAddress(network) — canonical USDC contract for a supported network.
• usdToAtomic(amount, decimals?) — safe USD → atomic-units conversion.
• encodePayment / decodePayment — base64 JSON codec for headers.

---

Development

npm install
npm run build     # bundles ESM + CJS + d.ts via tsup
npm run typecheck
npm test

To publish:

npm run build
npm publish

---

License

MIT Yeetful