name: circle-wallet
description: "Circle Programmable Wallets. Create and manage custodial wallets, transfer USDC, sign transactions via Circle API. Use when building wallet infrastructure."
metadata:
openclaw:
emoji: "🔵"

Circle Programmable Wallets

Create and manage custodial wallets via Circle's API. Agents can hold funds, transfer USDC, and sign transactions without managing raw private keys.

Setup

const CIRCLE_API = 'https://api.circle.com/v1/w3s';
const headers = {
  'Authorization': `Bearer ${process.env.CIRCLE_API_KEY}`,
  'Content-Type': 'application/json',
};

Core Operations

Create Wallet Set

const res = await fetch(`${CIRCLE_API}/developer/walletSets`, {
  method: 'POST',
  headers,
  body: JSON.stringify({ name: 'AgentHQ Wallets' }),
});
const { data: { walletSet } } = await res.json();

Create Wallet

const res = await fetch(`${CIRCLE_API}/developer/wallets`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    walletSetId: walletSet.id,
    blockchains: ['BASE'],
    count: 1,
    accountType: 'SCA', // Smart Contract Account
  }),
});
const { data: { wallets } } = await res.json();
const agentWallet = wallets[0]; // { id, address, blockchain }

Get Balance

const res = await fetch(`${CIRCLE_API}/wallets/${walletId}/balances`, { headers });
const { data: { tokenBalances } } = await res.json();
// [{ token: { symbol: 'USDC', ... }, amount: '10.50' }]

Transfer USDC

const res = await fetch(`${CIRCLE_API}/developer/transactions/transfer`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    walletId: sourceWalletId,
    tokenId: USDC_TOKEN_ID, // Circle's USDC token identifier
    destinationAddress: recipientAddress,
    amounts: ['1.00'],
    fee: { type: 'level', config: { feeLevel: 'MEDIUM' } },
  }),
});

Sign Transaction

const res = await fetch(`${CIRCLE_API}/developer/transactions/contractExecution`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    walletId,
    callData: encodedFunctionData,
    contractAddress: targetContract,
    fee: { type: 'level', config: { feeLevel: 'MEDIUM' } },
  }),
});

Wallet Types

Circle vs Self-Custodied

AgentHQ recommendation: Use self-custodied EOA for x402 payment signing (needs raw key access). Use Circle for treasury/cold storage where API-managed security is preferred.

References

• references/full-reference.md — Complete Circle API reference, webhook events, user-controlled wallets, compliance features
• Docs: https://developers.circle.com/w3s

Cross-References

• agent-wallet-management: Unified wallet operations
• cctp: Cross-chain USDC via Circle
• mcp-integration: Circle MCP server integration
• x402: Payment signing (requires key access — use EOA, not Circle)