BAC Agent Helper

This directory owns the Codex-side helper for the BAC mint flow. It is intentionally small and shells out to Coinbase Agentic Wallet's awal x402 pay command for the real x402 payment.

Commands

npx bacai --help
npx bacai manifest --manifest-file agent/examples/manifest.local.json
npx bacai mint --dry-run
npx bacai mint

npx bacai mint currently does three useful things:

• Fetches or reads the BAC challenge/manifest.
• Verifies the manifest asks for exactly 1 USDC.
• Verifies the manifest promises exactly 20,000 BAC.
• Verifies asset=USDC, scheme=exact, supported Base network, a non-expired manifest, and a non-zero x402 receiver.
• Runs npx awal@latest x402 pay against the mint URL unless --dry-run or --payment-header is used.

For production use, pin the expected receiver and host so Codex refuses to pay a spoofed manifest:

BAC_EXPECTED_PAY_TO=0x... \
BAC_EXPECTED_HOST=bacai.fun \
npx bacai mint

For backend integration tests, pass --payment-header or BAC_X402_PAYMENT_HEADER with an externally generated x402 PAYMENT-SIGNATURE header. The helper will POST the challenge to the mint API with that header.

Use BAC_AWAL_COMMAND=awal if awal is installed directly. The default is BAC_AWAL_COMMAND=npx and BAC_AWAL_PACKAGE=awal@latest.

Expected Manifest Shape

{
  "challengeId": "bac-challenge-id",
  "manifestHash": "sha256:...",
  "mintUrl": "https://api.example.com/api/bac/mint",
  "expiresAt": "2026-12-31T23:59:59.000Z",
  "payment": {
    "scheme": "exact",
    "network": "eip155:8453",
    "asset": "USDC",
    "amount": "1.00",
    "payTo": "0x..."
  },
  "allocation": {
    "symbol": "BAC",
    "amount": "20000"
  }
}

The backend can use a richer x402 requirements object, but it should preserve those semantic fields so agents can display and validate the offer before paying.