A card for your agent, with limits

1. Log in and create the account

Log in with Google, email, or a wallet and pick “Give my agent a wallet” in onboarding — or create an account any time under Agents in the dashboard. GenesisPay provisions a dedicated USDC wallet for the agent; you never handle a private key.

2. Fund it and set limits

The account page shows the wallet address and live USDC balance. On Base Sepolia (the current beta network), fund it for free from the Circle faucet at faucet.circle.com using the displayed address. Then set the spending policy: a per-payment cap and a daily cap (defaults 5 / 20 USDC), plus an optional monthly cap and an allowlist of origins or destination wallets the agent may pay.

Payments inside the caps settle automatically. Payments above a cap pause as pending approvals for you. Allowlist misses are hard blocked — no approval path.

3. Export a key and make the first payment

Issue an API key on the account's Keys tab. It starts with pp_ag_, is shown once, and is revocable without touching the wallet. Store it as PEERPAY_AGENT_KEYin your agent's environment, then pay any x402 URL:

curl -X POST "$PEERPAY_BASE_URL/api/v1/agent/pay" \
  -H "Authorization: Bearer pp_ag_your_agent_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/market-report",
    "maxAmountUsdc": "1.00"
  }'

{
  "paymentId": "3f2b...",
  "status": "settled",
  "txHash": "0x...",
  "response": {
    "status": 200,
    "mimeType": "application/json",
    "bodyBase64": "eyJyZXBvcnQiOiIuLi4ifQ=="
  },
  "payment": { "amountUsdcMinor": "500000", "resourceUrl": "https://..." }
}

GenesisPay fetches the URL, decodes the x402 payment requirement, checks it against your policy, signs the USDC transfer with the account wallet, and returns the paid resource with the body base64-encoded. maxAmountUsdcis the agent's own ceiling for this call — anything higher is rejected with 422 amount_exceeds_max before money moves.

The body accepts a few more optional fields. maxAmount is the asset-agnostic alias for the ceiling (it wins over the legacy maxAmountUsdc when both are set), and asset — one of USDC or EURC — restricts the payment to that stablecoin, so an endpoint advertising a different asset is rejected before settlement. Both USDC and EURC use 6 decimals, so the ceiling is expressed the same way for either. A description string can be attached for your own audit trail.

Tip: point the agent at a reusable GenesisPay link's payUrl from the seller quickstart for an instant end-to-end test.

Approvals: over-limit payments wait for you

When a payment exceeds a cap, the API returns 202 with pending_approval instead of moving money:

{
  "paymentId": "3f2b...",
  "status": "pending_approval",
  "approvalUrl": "https://your-peerpay-host/dashboard/approvals",
  "payment": { "status": "pending_approval" }
}

You approve or deny on the dashboard's Approvals page; approving executes the payment server-side. Pending approvals expire after 24 hours. A well-behaved agent reports approvalUrl to its human and polls GET /api/v1/agent/payments/:id until the status resolves.

Or use the SDK

import { PeerPayAgent } from "@genesis-tech/peerpay-agent";

const agent = new PeerPayAgent({
  apiKey: process.env.PEERPAY_AGENT_KEY!,
  baseUrl: process.env.PEERPAY_BASE_URL!,
});

const result = await agent.pay("https://api.example.com/market-report", {
  maxAmountUsdc: "1.00",
  // Optionally block until a human approves an over-limit payment:
  waitForApproval: { timeoutMs: 300_000, pollIntervalMs: 5_000 },
});

if (result.status === "settled") {
  // json()/body()/bytes() are synchronous — the resource body is already
  // captured on the result, so there is nothing to await.
  const report = result.json();
} else if (result.status === "pending_approval") {
  // Surface result.approvalUrl to the human and poll later.
}

agent.account() returns the wallet address, USDC balance, policy, and spend totals — useful for an agent to check its budget before committing to a task. agent.discover(query) searches the public directory for payable services.