Appearance
Fund and withdraw collateral
A cardholder's cards share a collateral balance. You can fund it by sending an accepted token to the application's deposit address, or ask Agio to transfer funds from your configured treasury. Treasury-managed collateral can also be withdrawn back to that treasury.
Direct deposit
Read the funding address from the card application. Wait until deposit_address and deposit_chain_id are populated; do not substitute the collateral-admin wallet_address or a personal wallet.
graphql
query DepositAddress($applicationId: Int!) {
AgioCard_card_application(where: { id: { _eq: $applicationId } }, limit: 1) {
id
card_user_id
application_status
deposit_address
deposit_chain_id
}
}json
{ "applicationId": 42 }Send the token accepted by your program to deposit_address on deposit_chain_id. Confirm the token contract with Agio during setup. Production collateral commonly uses USDC on Base (8453); development can use Ethereum Sepolia (11155111) or Base Sepolia (84532) and test tokens such as rUSD. Read the actual application chain rather than hardcoding the example network.
A deposit address is the collateral destination, separate from the wallet that administers it. Both treasury-managed and customer-supplied collateral-admin applications can receive a deposit address after contract provisioning.
After confirmation on-chain, check both the deposited token balance and resulting spending power. A confirmed transfer does not by itself establish that the issuer has credited the cardholder.
Check balances
The read surfaces use different units:
| Surface | Units |
|---|---|
AgioCard_vw_card_token_balance.token_balance | Token units |
AgioCard_vw_card_token_balance.token_balance_usd | USD |
AgioCard_vw_card_user_balance monetary fields | Integer cents |
cardBalance.balance monetary fields | USD |
Funding and withdrawal amountCents | Integer cents |
For example, spending power of $15.71 is 15.71 in cardBalance and 1571 in AgioCard_vw_card_user_balance.spending_power.
graphql
query CollateralBalances($where: AgioCard_vw_card_token_balance_bool_exp!) {
AgioCard_vw_card_token_balance(where: $where) {
deposit_address
chain_name
token_symbol
token_balance
token_balance_usd
advance_rate
}
}json
{ "where": { "deposit_address": { "_eq": "<application deposit_address>" } } }The balance view shows the collateral held on-chain. advance_rate records how much of the collateral's value can contribute to credit.
graphql
query SpendingBalance($cardUserId: String!) {
AgioCard_vw_card_user_balance(where: { card_user_id: { _eq: $cardUserId } }) {
card_user_id
credit_limit
collateral_balance
spending_power
balance_due
}
}json
{ "cardUserId": "<cardUserId from createPartnerCardUser>" }Use the numeric Agio card ID for a live issuer balance:
graphql
query LiveBalance($cardId: Int!) {
cardBalance(cardId: $cardId) {
success
id
balance {
creditLimit
pendingCharges
postedCharges
spendingPower
balanceDue
}
error
}
}json
{ "cardId": 86 }Pending authorizations reduce spending power before a purchase settles. Use transaction events to explain changes to the cardholder.
Fund from treasury
cardFundSubClientFromTreasury transfers collateral from your treasury into a cardholder's collateral contract. Your treasury configuration sets the chain, so the request has no chainId input.
Supply the issuer cardholder UUID as externalUserId. That is the application's card_user_id, also returned as cardApplicationExternalId. Do not use the provisioned cardUserId from createPartnerCardUser here.
graphql
mutation Fund($input: CardFundSubClientFromTreasuryInput!) {
cardFundSubClientFromTreasury(input: $input) {
success
jobId
errorCode
error
}
}json
{ "input": { "externalUserId": "<the application card_user_id>", "amountCents": 50000, "idempotencyKey": "fund-2026-11-12-0001" } }50000 funds $500. Agio does not check your treasury balance when it accepts the request, so read your treasury balance first. success: true means the funding job started, not that funds arrived. Save jobId and read its status.
idempotencyKey is optional. It takes 8 to 128 letters, digits, dashes or underscores, and it is scoped to your organization. A request with a key you used before creates no job and returns the jobId of the first one. Use a new key for a new funding.
Job status
graphql
query FundingStatus($jobId: String!) {
cardFundSubClientStatus(jobId: $jobId) {
success
jobId
status
txHash
failedCode
failedReason
errorCode
errorMessage
}
}json
{ "jobId": "<funding jobId>" }A funding job reaches completed, failed or submitted within about two minutes.
pendingorrunning: in progress. Wait and read the status again.completed: final.txHashholds the transaction hash.failed: nothing was sent, so it is safe to send again.submitted: the outcome is unknown. Do not send again. Agio resolves it.cancelled: final. A job is cancelled only after you cancel it while it is failed.
Cancel a failed job
cardFundSubClientCancel(jobId) returns the same fields as cardFundSubClientStatus. It moves a failed job to cancelled. For any other status it changes nothing and returns errorCode: "NOT_CANCELLABLE" with the current status.
Funding error codes
| Where | Code | Meaning |
|---|---|---|
cardFundSubClientFromTreasury.errorCode | INVALID_AMOUNT | Supply a positive integer amountCents |
cardFundSubClientFromTreasury.errorCode | SUBCLIENT_NOT_FOUND | Check the cardholder ID and your partner scope |
cardFundSubClientFromTreasury.errorCode | TREASURY_NOT_CONFIGURED | Contact Agio to configure the treasury |
cardFundSubClientFromTreasury.errorCode | INVALID_IDEMPOTENCY_KEY | Use 8 to 128 letters, digits, dashes or underscores |
cardFundSubClientFromTreasury.errorCode | IDEMPOTENCY_KEY_REUSED | The key belongs to a request with another cardholder or amount |
failedCode on a failed job | COLLATERAL_CONTRACT_NOT_READY | The cardholder's collateral contract does not exist yet |
failedCode on a failed job | FUNDING_SIGNER_REFUSED | The transfer was declined before it was sent |
failedCode on a failed job | FUNDING_EXPIRED | The transfer was not sent in time |
failedCode on a failed job | FUNDING_NOT_SENT | The job stopped before it sent anything |
failedCode on a failed job | Funding transaction ... | The transfer was rejected on-chain and moved no funds |
failedCode on a submitted job | FUNDING_SEND_INDETERMINATE | The outcome is unknown. Do not send again |
cardFundSubClientStatus.errorCode | FORBIDDEN, NOT_FOUND, INTERNAL_ERROR | The caller is not a partner, the job is not yours, or the read failed |
cardFundSubClientCancel.errorCode | FORBIDDEN, NOT_FOUND, NOT_CANCELLABLE, INTERNAL_ERROR | The caller is not a partner, the job is not yours, it is not failed, or the change failed |
A failed job can carry other codes, such as SUBCLIENT_NOT_FOUND or TREASURY_WALLET_MISMATCH. Every code on a failed job means nothing was sent. Do not branch on the text of failedReason.
Send again safely
To retry, send the same call with the same idempotency key.
After failed, cancel the job first. Use a new key only when cancel returns cancelled.
Withdraw to treasury
cardWithdrawForPartner withdraws collateral into your configured treasury wallet. The treasury must be the cardholder's collateral admin, as configured with createWallet: true during application setup. It cannot sign a withdrawal from a customer's self-custody collateral admin.
The destination is fixed by your treasury configuration. The request has no destination-address field. Unlike treasury funding, this operation returns its on-chain result directly.
graphql
mutation Withdraw($input: CardWithdrawForPartnerInput!) {
cardWithdrawForPartner(input: $input) {
success
transactionHash
spendingPowerCents
requestedCents
retryAfterSec
errorCode
error
}
}json
{
"input": {
"externalUserId": "<cardUserId from createPartnerCardUser>",
"amountCents": 50000,
"dryRun": true
}
}dryRun: true checks inputs, scope, treasury configuration and issuer spending power only. It does not simulate the on-chain withdrawal, so a passing dry run does not guarantee the real call succeeds. An on-chain failure returns success: false with an error message and no errorCode. Read spendingPowerCents when present; a dry run does not reserve funds or guarantee that a later withdrawal succeeds. To submit, use the same operation with dryRun: false. Store transactionHash on success and reconcile the collateral decrease.
An optional chainId defaults to the treasury's configured chain. Use a chain configured for your program. The optional vasp field supports a receiving-VASP Travel Rule integration; coordinate that setup with Agio if you need it.
| Error code | Action |
|---|---|
INVALID_AMOUNT | Supply a positive integer amountCents |
SUBCLIENT_NOT_FOUND | Check the cardUserId and partner scope |
TREASURY_NOT_CONFIGURED | Contact Agio to configure the treasury |
INSUFFICIENT_SPENDING_POWER | Compare spendingPowerCents with requestedCents |
CARD_SIGNING_IN_FLIGHT | Wait for retryAfterSec before retrying |
ADMIN_MISMATCH | Contact Agio. Your treasury is not this cardholder's card admin |
INTERNAL_ERROR | Check configuration and reconcile any uncertain outcome with Agio |
For bulk funding, multisend sends from a smart wallet to several deposit addresses in one batch. Collateral webhooks report deposits and withdrawals without an individual card ID.
Transfer between cardholders
cardTransferForPartner moves collateral from one of your cardholders to another of your cardholders. Your treasury signs as the source cardholder's collateral admin. The withdrawal goes from the source collateral contract straight to the recipient's card deposit address. Agio reads that address from the card program. The request has no destination-address field.
graphql
mutation Transfer($input: CardTransferForPartnerInput!) {
cardTransferForPartner(input: $input) {
success
transferId
status
transactionHash
chainId
amountCents
feeMillicents
retryAfterSec
errorCode
error
}
}json
{
"input": {
"source": "<a reference to the sending cardholder>",
"recipient": "<a reference to the receiving cardholder>",
"amountCents": 2500,
"idempotencyKey": "transfer-2026-10-12-0001"
}
}chainId and tokenAddress are optional. They default to your treasury configuration. Both cardholders must have one collateral contract on that chain that holds that token, and the token must be a USD stablecoin.
Cardholder references
source and recipient each take any of these four forms. You do not name the form.
| Form | Example field |
|---|---|
| Agio user ID | userId of the cardholder |
| Cardholder ID | cardUserId from createPartnerCardUser |
| Card ID | the card's external UUID |
| Card number (PAN) | the full card number, with or without spaces or dashes |
A card ID or a card number refers to the cardholder's shared balance. It is not a separate card balance. A card reference must point to a current card with status active. Agio does not follow a replaced card to its replacement.
A cardholder can never send to itself. When source and recipient resolve to the same cardholder, through any mix of IDs or card numbers, the call fails with SAME_CARDHOLDER. Both cardholders must be approved and active, and each must have an active card. Otherwise the call fails with CARDHOLDER_NOT_ACTIVE or CARD_NOT_ACTIVE. Agio never stores, logs or returns a card number.
When several forms match the same cardholder, the reference resolves to that cardholder. When a reference matches two different cardholders, the call fails with AMBIGUOUS_REFERENCE. A reference that matches no cardholder in your scope returns CARDHOLDER_NOT_FOUND, also when the cardholder belongs to another partner.
Status and safe retries
status | Meaning |
|---|---|
processing | The withdrawal is submitted, or its outcome is still being reconciled |
in_transit | The withdrawal is final on-chain, and the recipient's collateral credit is not recorded yet |
complete | The token transfer is final and the card program credited the recipient |
error | No funds moved. Read errorCode and error |
success is true only while the transfer has no open errorCode. To read the latest status, send the same request again with the same idempotencyKey. A status read does not check the cards or the treasury configuration again. The call returns the existing transfer and never moves funds twice. A different payload with a used key fails with IDEMPOTENCY_KEY_REUSED. Each source cardholder has at most one transfer in processing. A second transfer from the same source returns TRANSFER_IN_PROGRESS until the first one leaves processing. When the withdrawal outcome is unknown, the transfer stays in processing with errorCode: WITHDRAWAL_UNCONFIRMED, and Agio reconciles it. Do not send a new transfer to replace it.
Fees
A transfer has no fee unless your card fee schedule has an active card_transfer rule. Such a rule can charge a flat amount, a percentage of the amount, or both. The source cardholder pays it on the card fee ledger. Agio quotes the fee when it creates the transfer and returns it in feeMillicents. The fee counts against the source cardholder's withdrawable collateral. The recipient's credit from a transfer does not add a load fee.
| Error code | Action |
|---|---|
INVALID_AMOUNT | Supply a positive integer amountCents |
INVALID_IDEMPOTENCY_KEY | Use 16 to 64 letters, digits, dashes or underscores |
CARDHOLDER_NOT_FOUND | Check the reference and your partner scope |
AMBIGUOUS_REFERENCE | Use a reference that names one cardholder, such as the cardholder ID |
CARD_NOT_ACTIVE | Use an active current card. Each cardholder needs one |
CARDHOLDER_NOT_ACTIVE | Both cardholders must be approved and active |
SAME_CARDHOLDER | Source and recipient must be different cardholders with different contracts |
CONTRACT_NOT_FOUND | Check the chain and token for both cardholders |
CONTRACT_AMBIGUOUS | Contact Agio. The cardholder has more than one contract for the token |
UNSUPPORTED_TOKEN | Use the USD stablecoin collateral token of your program |
CARD_INSUFFICIENT_COLLATERAL | Lower the amount. Pending card spend and open fees are not withdrawable |
TREASURY_NOT_CONFIGURED | Contact Agio to configure the treasury |
IDEMPOTENCY_KEY_REUSED | Use a new key for a new transfer |
TRANSFER_IN_PROGRESS | Wait until the open transfer from this source leaves processing |
CARD_SIGNATURE_ACTIVE | Wait for retryAfterSec, then retry with a new key |
WITHDRAWAL_UNCONFIRMED | Do not retry. Agio reconciles the transfer |