Cards

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)
});

card = sdk.cards.cards_create(
    purpose="Research Agent",
    limit_amount=50,
    network="eip155:8453",
    asset="USDC",
    single_use=False,
    expires_in=24,
)

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",
});

test_card = sdk.cards.cards_create(
    purpose="Testing Agent",
    limit_amount=100,
    network="eip155:84532",  # Base Sepolia = sandbox
    asset="USDC",
)

How it works

{
  "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.

Getting Started

Core Concepts

Protocols Deep Dive

Agent Integration

SDKs

Overview

Card lifecycle

Issue a card

Bulk issuance

Spending controls

MCC locks

Freeze / unfreeze

Move funds back to treasury

Close a card

Audit trail

Sandbox & testnet

How it works

Same API key, same endpoints

​Overview

​Card lifecycle

​Issue a card

​Bulk issuance

​Spending controls

​MCC locks

​Freeze / unfreeze

​Move funds back to treasury

​Close a card

​Audit trail

​Sandbox & testnet

​How it works

​Same API key, same endpoints

Overview

Card lifecycle

Issue a card

Bulk issuance

Spending controls

MCC locks

Freeze / unfreeze

Move funds back to treasury

Close a card

Audit trail

Sandbox & testnet

How it works

Same API key, same endpoints