PayDirect
Sign InGet Started
Guide

Coinbase Agentic Wallets

Give your AI agent a self-custody wallet to pay for PayDirect invoices and x402-protected APIs — with spending limits, gasless trading, and Base-native USDC transfers.

How This Fits PayDirect

PayDirect already supports agent payments through two channels that work with Coinbase Agentic Wallet out of the box — no new payment rail or checkout changes required:

x402 pay-per-request

Agentic Wallet's awal x402 pay command auto-pays PayDirect's existing x402 routes. See x402 Protocol Payments for protocol details.

Direct USDC to invoices

Create a PayDirect payment via REST or SDK, then send USDC with awal send. PayDirect's CDP webhooks detect the transfer on Base automatically.

Prerequisites

  • Node.js 24+
  • An email address for Agentic Wallet OTP authentication
  • A PayDirect workspace with API keys (pd_test_ or pd_live_)
  • USDC on Base in the agent wallet (fund via Coinbase or onramp)

Official docs: Coinbase Agentic Wallet

Setup: Authenticate the Agent Wallet

# Install agent skills (optional, for AI agents) npx skills add coinbase/agentic-wallet-skills # Start login — sends OTP to email npx awal auth login [email protected] # Complete with flowId + 6-digit code from email npx awal auth verify <flowId> <otp> # Confirm wallet is ready npx awal status npx awal balance npx awal address

Pattern A: x402 Pay-Per-Request

PayDirect exposes x402-protected demo endpoints. An agent with Agentic Wallet can pay and consume them in one command — no PayDirect API key required on the buyer side.

# Pay $0.001 for weather data (sandbox / base-sepolia) npx awal x402 pay https://www.paydirect.com/api/x402/weather # Pay $0.01 for premium content npx awal x402 pay "https://www.paydirect.com/api/x402/content?topic=agentic-wallets"

Under the hood: the route returns HTTP 402, Agentic Wallet signs the payment, the Coinbase facilitator settles on-chain, and PayDirect records the settlement via its x402 bridge.

Pattern B: Pay a PayDirect Invoice with USDC

For invoice-style payments (custom amounts, webhooks, hosted checkout), use the PayDirect REST API to create a payment, then send USDC from the agent wallet to the receivingAddress.

1. Seller creates payment (PayDirect API)

curl -X POST https://www.paydirect.com/api/v1/payments \ -H "Authorization: Bearer pd_live_..." \ -H "Content-Type: application/json" \ -d '{ "tokenSymbol": "USDC", "amount": "5.00", "description": "Agent service fee", "metadata": { "orderId": "AGT-001" } }' # Response includes: # receivingAddress — send USDC here on Base # paymentUrl — hosted checkout link # payment.id — track status via GET /api/v1/payments/:id

2. Buyer agent pays with Agentic Wallet

# Send exact USDC amount to the receiving address from step 1 npx awal send 5 0xReceivingAddressFromPayDirect... # JSON output for programmatic agents npx awal send 5 0xReceivingAddress... --json

3. Verify settlement

PayDirect detects the on-chain transfer, confirms after 12 blocks, deducts fees, and forwards net proceeds to your settlement address. Poll status or use webhooks:

curl https://www.paydirect.com/api/v1/payments/<paymentId> \ -H "Authorization: Bearer pd_live_..." # Or verify explicitly: curl -X POST https://www.paydirect.com/api/v1/verify \ -H "Authorization: Bearer pd_live_..." \ -H "Content-Type: application/json" \ -d '{ "paymentId": "<paymentId>" }'

See also: Agent-to-Agent Payments for a full buyer/seller REST flow with demo scripts.

Pattern C: Combined AI Tools

Use PayDirect tools for invoicing and Agentic Wallet skills for spending — together in a Vercel AI SDK agent.

npm install @paydirectv2/ai-sdk ai zod npx skills add coinbase/agentic-wallet-skills import { generateText } from "ai"; import { createPayDirectTools } from "@paydirectv2/ai-sdk"; const paydirect = createPayDirectTools({ apiKey: process.env.PAYDIRECT_API_KEY!, baseUrl: "https://www.paydirect.com/api/v1", }); // Agent can: // - createPayment / getPayment (PayDirect tools) // - send / x402 pay (Agentic Wallet skills via awal CLI) const result = await generateText({ model: yourModel, tools: { ...paydirect }, prompt: "Create a 2 USDC payment for order AGT-002, then pay the receiving address with awal send", });

PayDirect AI tools: AI Frameworks docs

Spending Limits & Security

  • Agentic Wallet enforces per-session and per-transaction spending caps before any send
  • Private keys stay in Coinbase infrastructure — agents never hold raw keys
  • Transfers are screened (KYT / OFAC) before submission on-chain
  • PayDirect API keys should remain server-side; only the agent wallet signs outbound USDC
  • Use sandbox (pd_test_) and Base Sepolia x402 routes before going live

Troubleshooting

awal: not authenticated

Run npx awal auth login and verify OTP. Check with npx awal status.

Insufficient USDC balance

Fund the wallet on Base. Use Coinbase Onramp or transfer USDC to the address from awal address.

Payment stuck in pending

Confirm the exact amount was sent to receivingAddress on Base (not another network). Allow ~2 minutes for detection and 12-block confirmation.

x402 pay fails

Ensure the agent wallet has USDC on the route's network (demo routes use base-sepolia). See x402 guide.

More help: Troubleshooting guide

Related Docs