Skip to main content

​
Overview

Cards are the core primitive. Each card is a virtual payment instrument backed by your USDC or pathUSD treasury balance. Agents use cards to pay for APIs, services, and resources.

​
Card lifecycle

CLOSED is a terminal, one-way state. A closed card stops working immediately and leaves the wallet view, but its records are never deleted: full history stays available through the account activity feed.

​
Issue a card

const card = await mag3nt.cards.cardsCreate({
  purpose: "Research Agent",
  limitAmount: 50,        // Max spend (USDC/pathUSD)
  network: "eip155:8453", // Base
  asset: "USDC",
  singleUse: false,       // Reusable
  expiresIn: 24,          // Hours (0 = never)
});

​
Bulk issuance

Create up to 1,000 cards atomically: 
const batch = await mag3nt.cards.cardsBulkCreate({
  cards: [
    { purpose: "Agent Alpha", limitAmount: 25 },
    { purpose: "Agent Beta", limitAmount: 25 },
    { purpose: "Agent Gamma", limitAmount: 50 },
  ],
  network: "eip155:8453",
  asset: "USDC",
});
// All-or-nothing: if total exceeds balance, none are created

​
Spending controls

​
MCC locks

Restrict which merchant categories a card can pay: 
await mag3nt.cards.cardsUpdateControls(cardId, {
  mccLocks: "5411,5812", // Only grocery and restaurants
});

​
Freeze / unfreeze

Instantly block all transactions on a compromised card: 
await mag3nt.cards.cardsFreeze(cardId);
// Card is immediately blocked:no payments can process

await mag3nt.cards.cardsUnfreeze(cardId);
// Card is restored to ACTIVE

​
Move funds back to treasury

Sweep a card’s unspent balance back into your treasury, where it can be withdrawn off-platform. For EXPIRED cards this always performs a full sweep. For ACTIVE or FROZEN cards, omit the amount to sweep everything, or pass an amount for a partial claim (the card stays active with the remainder). Pending charges and mandate holds are excluded from the sweepable balance, so a claim can never strand an in-flight payment. 
// Full sweep
await mag3nt.cards.cardsClaim(cardId);

// Partial claim: pull $5 back, leave the rest on the card
await mag3nt.cards.cardsClaim(cardId, { amount: 5 });

​
Close a card

Retire a card you no longer need. Closing is a one-way action allowed only when the card is empty and has no open obligations:
  • Remaining balance is zero (sweep with a claim first if needed)
  • No in-flight pending transaction
  • No open payment stream
  • No active, unexpired AP2 mandate
await mag3nt.cards.cardsClose(cardId);
A closed card disappears from the wallet view. Its history is preserved and remains accessible from the account activity feed.

​
Audit trail

Every transaction is recorded with full metadata. Read a single card’s history, or the whole wallet’s activity across every card (including closed ones): 
// One card
const txns = await mag3nt.cards.cardsListTransactions(cardId);
for (const txn of txns.transactions) {
  console.log(`${txn.amount} USDC/pathUSD to ${txn.merchant} via ${txn.protocol}`);
}

// All cards, including closed: each row is tagged with card_purpose and card_status
const all = await mag3nt.transactions.list();

​
Sandbox & testnet

mag3nt uses network-based environment isolation:no separate test API keys needed. Issue a card on a testnet network to activate sandbox mode: 
const testCard = await mag3nt.cards.cardsCreate({
  purpose: "Testing Agent",
  limitAmount: 100,
  network: "eip155:84532",  // Base Sepolia = sandbox
  asset: "USDC",
});

​
How it works

| eip155:8453 (Base) | production | Real USDC | | solana:mainnet (Solana) | production | Real USDC | | eip155:4217 (Tempo) | production | Real USDC or pathUSD | | eip155:84532 (Base Sepolia) | sandbox | Test USDC:no real value | Every payment response includes an environment field: 
{
  "success": true,
  "environment": "sandbox"
}
Sandbox transactions deduct from your card balance just like production, but use test tokens with no real value. Use sandbox to validate your integration before going live.

​
Same API key, same endpoints

Your API key works for both environments. The card’s network is the boundary:not the key, not the endpoint. A single account can have both mainnet and testnet cards simultaneously.