Fund platform cards

Deposit stablecoins as collateral to fund a card, or withdraw available collateral to the user's wallet. This guide uses platform user authentication.

For partner treasury transfers or direct deposits, use partner funding.

Deposit flow (Wallet to card)

Funding a card is a two-step process: get a swap quote, then execute it. The swap converts tokens from the user's smart wallet into USDC and sends them to the Agio collateral address.

Step 1: verify funding wallet

Use an EVM smart wallet that the authenticated user can operate on the selected chain. Use the wallet ID returned when you create the wallet.

Step 2: get a swap quote

Request a quote to convert tokens into USDC for the card collateral:

mutation SmartWalletSwapQuote($input: SmartWalletSwapInput!) {
  smartWalletSwapQuote(input: $input) {
    success
    quote {
      quoteId
      fromAmount
      minimumToAmount
      expiry
      priceImpactPct
      amountInUsd
      amountOutUsd
      networkFeeUsd
      estimatedFillSeconds
      route {
        provider
        providersQueried
      }
    }
    error
  }
}

{
  "input": {
    "digitalWalletId": "123",
    "fromToken": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "toToken": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "amount": "100000000",
    "recipient": "0xCardCollateralAddress..."
  }
}

Field	Description
digitalWalletId	The user's smart wallet ID
fromToken	Token contract address to swap from
toToken	USDC contract address (destination)
amount	Amount in wei (smallest unit). For USDC with 6 decimals, 100000000 = 100 USDC.
recipient	Agio collateral wallet address. When set, swap output goes directly to this address.
providers	Optional. Array of swap providers to query (e.g., ["RELAY", "ALCHEMY"]). Defaults to best-route selection.

Step 3: execute the swap

After the user reviews and confirms the quote, execute it:

mutation SmartWalletExecuteSwapQuote($input: SmartWalletExecuteSwapQuoteInput!) {
  smartWalletExecuteSwapQuote(input: $input) {
    success
    transactionHash
    quoteId
    status
    error
  }
}

{
  "input": {
    "quoteId": 456
  }
}

The quoteId is returned from the swap quote response. Quotes have an expiry — if the quote has expired, request a new one.

Confirm funding

Check the returned transaction hash and status. Read the card balance after the deposit confirms.

Withdrawal flow (Card to wallet)

Withdraw available collateral from the card wallet back to the user's wallet.

Execute a withdrawal

mutation CardWithdraw($input: CardWithdrawInput!) {
  cardWithdraw(input: $input) {
    success
    transactionHash
    chainId
    tokenAddress
    amount
    error
    retryAfterSec
  }
}

{
  "input": {
    "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amount": "100.5",
    "chainId": 8453
  }
}

Field	Type	Description
tokenAddress	String!	ERC-20 token contract address to withdraw (e.g., USDC on Base: 0x8335...2913)
amount	String!	Human-readable amount (e.g., "100.5" for 100.5 USDC)
chainId	Int	Chain ID to withdraw from (Base mainnet = 8453). When omitted, resolved by matching tokenAddress across supported chains.

Signature Conflicts

If the withdrawal fails with a retryAfterSec value, an Agio signature is currently active. Display the delay and retry after the returned number of seconds.

Balance queries

Single card balance

Pass the internal card ID to read its cardholder's balance. The issuer balance belongs to the cardholder, rather than to one card's spending limit:

query AgioCardBalance($cardId: Int!) {
  cardBalance(cardId: $cardId) {
    success
    id
    balance {
      creditLimit
      pendingCharges
      postedCharges
      balanceDue
      spendingPower
    }
    error
  }
}

Balance fields

Field	Type	Description
creditLimit	Float	Total credit limit based on deposited collateral (USD)
pendingCharges	Float	Authorized but not yet settled transactions (USD)
postedCharges	Float	Settled transactions (USD)
balanceDue	Float	Amount currently owed (USD)
spendingPower	Float	Available to spend: creditLimit - pendingCharges - postedCharges (USD)

Example balance

For a cardholder with $1,000 in collateral and $150 in pending purchases:

{
  "creditLimit": 1000.0,
  "pendingCharges": 150.0,
  "postedCharges": 0.0,
  "balanceDue": 0.0,
  "spendingPower": 850.0
}