Agents

All agent lifecycle calls live on client.agents. Every operation is project-scoped via the API key — you don’t pass a project ID anywhere.

agents.create(input)

Creates a new agent wallet (or returns the existing one if agentId is already taken).

const agent = await client.agents.create({
  agentId:     'trading-bot-1',         // required — your stable, unique-per-project identifier
  displayName: 'Arb trading bot',       // optional — for the dashboard
  chain:       'avalanche',             // optional — defaults to your tier's primary chain
});

Returns

{
  "agentId":      "trading-bot-1",
  "address":      "0xb0e6ec46cd2d97de006f9318ac5c7994b7aadd2b",
  "projectId":    "proj_7f7c8906ce5d1bad",
  "developerId":  "c01ca9ac-d0f1-7085-a5e7-f8d2154d61e8",
  "displayName":  "Arb trading bot",
  "chain":        "avalanche",
  "custodyType":  "hd",                 // 'hd' on Free/Builder, 'kms' on Enterprise
  "tierAtCreate": "free",
  "policy": {
    "perTxCapUSD":          5,
    "perDayCapUSD":         50,
    "allowedTokens":        ["USDC"],
    "allowedChains":        ["fuji"],
    "requireMainnetCredit": true
  },
  "status":    "active",
  "existing":  false,                   // true on subsequent create() with same agentId
  "createdAt": "2026-06-08T20:14:09.915Z"
}

Constraints

Rule	Notes
agentId is alphanumeric + _ + -, max 64 chars	^[A-Za-z0-9_-]{1,64}$
Idempotent on agentId	Calling twice with the same id returns the same agent — existing: true.
Per-tier agent cap	Free 5, Builder 20, Enterprise custom. Over the cap → 403.
x402 must be enabled first	Otherwise 403 with x402Enabled: false. Call client.policy.enableX402() once.
Chain must be allowed by tier	Free is Fuji only; Builder adds Avalanche; Enterprise can add Base.

Errors

Status	When
400	Missing or invalid agentId; chain not allowed for your tier.
403	x402 not enabled, OR agent cap reached. The error body includes tier, limit, current.
404	Project not found (rare — only if the API key is somehow orphaned).

agents.list(opts?)

Returns every agent in the project, with pagination.

const { agents, count, projectId, nextCursor } = await client.agents.list({
  status: 'active',          // 'active' | 'paused' | 'revoked' | 'all' (default: 'all')
  limit:  50,                // default 50, max 200
  cursor: previousCursor,    // pagination
});

Returns

{
  "agents": [
    {
      "agentId":     "trading-bot-1",
      "address":     "0xb0e6...dd2b",
      "displayName": "Arb trading bot",
      "chain":       "avalanche",
      "custodyType": "hd",
      "status":      "active",
      "policy":      { /* full policy snapshot */ },
      "identity":    null,
      "createdAt":   "2026-06-08T20:14:09.915Z",
      "updatedAt":   "2026-06-08T20:14:09.915Z"
    }
    // …
  ],
  "count":      27,
  "projectId":  "proj_7f7c8906ce5d1bad",
  "nextCursor": "eyJwayI6Ii4uLiJ9"      // present only when more pages exist
}

Pass nextCursor into the next call as cursor to fetch the next page.

agents.get(agentId)

Fetch a single agent by ID. Lightweight, no on-chain reads.

const agent = await client.agents.get('trading-bot-1');
// → same shape as a single row from list()

Errors

Status	When
404	Agent doesn’t exist in your project.

agents.getBalance(agentId, opts?)

Reads the agent’s on-chain USDC balance via an eth_call to the token contract. Fast, cached briefly.

// Default — query the agent's home chain
const b = await client.agents.getBalance('trading-bot-1');

// Or query every chain in the agent's policy
const all = await client.agents.getBalance('trading-bot-1', { chain: 'all' });

Returns

{
  "agentId":   "trading-bot-1",
  "address":   "0xb0e6ec46cd2d97de006f9318ac5c7994b7aadd2b",
  "projectId": "proj_7f7c8906ce5d1bad",
  "balances": {
    "fuji": {
      "usdc":     "0.500000",          // human-readable, 6-decimal string
      "atomic":   "500000",            // raw uint256 in token base units
      "chainId":  43113,
      "token":    "0x5425890298aed601595a70AB815c96711a31Bc65",
      "symbol":   "USDC",
      "decimals": 6
    }
  }
}

When you pass chain: 'all', the balances map contains one entry per chain in the agent’s allowedChains. If an RPC call fails for a specific chain, that chain’s entry will contain error instead of usdc.

agents.revoke(agentId)

Terminally blocks an agent from signing new x402 payments.

await client.agents.revoke('trading-bot-1');

Returns

{
  "agentId":   "trading-bot-1",
  "projectId": "proj_7f7c8906ce5d1bad",
  "status":    "revoked",
  "address":   "0xb0e6ec46cd2d97de006f9318ac5c7994b7aadd2b",
  "revokedAt": "2026-06-10T14:56:26.822Z",
  "alreadyRevoked": false               // true on subsequent calls — idempotent
}

Important caveat about revoke + EIP-3009

Revoke prevents the agent from producing new signatures. It cannot recall authorizations the agent already signed and that haven’t yet been settled on-chain — those remain redeemable by the recipient until their validBefore expires.

This is inherent to EIP-3009: the only way to cancel an outstanding authorization is for the agent itself to sign a cancelAuthorization call, which we can’t do post-revoke. The SDK sets a short default validBefore window (5 minutes) for exactly this reason — minimise exposure.

If you need to invalidate a still-pending payment, settle a small reversing payment or wait for the window to expire.

agents.activity(agentId, opts?)

Query recent verify + settle events for an agent. See Activity for the full reference.

const recent = await client.agents.activity('trading-bot-1', { days: 7, limit: 50 });

Patterns

Create-or-get on app start

// Safe to call on every cold start — idempotent.
const agent = await client.agents.create({ agentId: 'my-bot', chain: 'fuji' });

Get all active agents across paginated results

const all = [];
let cursor: string | undefined;
do {
  const page = await client.agents.list({ status: 'active', limit: 200, cursor });
  all.push(...page.agents);
  cursor = page.nextCursor;
} while (cursor);

Display USDC balance in your UI

const { balances } = await client.agents.getBalance('trading-bot-1');
const usdc = Number(balances.fuji?.usdc || '0').toFixed(2);
console.log(`Agent has ${usdc} USDC`);

See also

• Payments — how to actually spend the balance.
• Policy — change caps and allowed chains.
• Errors — full error reference.