Deposited USDC Credits

Deposit USDC once, spend it like credit, and withdraw whatever you did not use. It is the only funded balance on Surplus that can leave again. (Elsewhere in the API and the dashboard this is called prefunded USDC — same thing.)

Card top-ups create credit — an internal ledger balance that can be spent and never withdrawn. Prefunded USDC is the other half: you send USDC to a deposit address owned by your workspace, it becomes a spendable balance, and the unspent remainder can go back to your wallet.

The distinction that matters

Both balances add up to one spendable number in the dashboard. Underneath they are not interchangeable.

That is also why the spend order is what it is: card credit is spent first, prefunded USDC second. Spending the non-withdrawable money first preserves the withdrawable money for as long as possible. If the order were reversed, every request would quietly convert money you could get back into money you could not.

Depositing

curl -s https://api.surplusintelligence.ai/v1/payments/deposit-address \
  -H "Authorization: Bearer inf_..."

curl -s $SURPLUS_BASE_URL/payments/deposit-address \
  -H "Authorization: Bearer inf_..."

The address is per workspace and stable — reuse it. Send USDC on Base to it from any wallet. The balance is not spendable the moment the transaction lands: it is credited after the configured minimum confirmations, which exists so a reorg cannot spend money that never settled.

Requires billing.manage.

Withdrawing

curl -s -X POST https://api.surplusintelligence.ai/v1/payments/withdraw \
  -H "Authorization: Bearer inf_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{ "destination": "0xYourWallet", "amount_micro": "25000000" }'

curl -s -X POST $SURPLUS_BASE_URL/payments/withdraw \
  -H "Authorization: Bearer inf_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{ "destination": "0xYourWallet", "amount_micro": "25000000" }'

• destinationstring

  Where the USDC goes. Not a free-text field — it must be your own account wallet or a wallet the org has registered. An address that is neither is rejected, so a leaked key cannot drain funds to an attacker.

• amount_microstring

  Integer microdollars as a string (1 USD = 1000000). Omit to withdraw everything available. A string because a JSON number silently accepts 1.5, and a fractional microdollar is not a representable amount of USDC.

Idempotency-Key is required and becomes the withdrawal's permanent identity, so a retried request can never withdraw twice. Requires wallets.manage — deliberately a different capability from billing.manage, because taking money out is a different decision from putting money in.

For a signed, multi-step withdrawal there is also POST /v1/wallet/withdraw/prepare, POST /v1/wallet/withdraw and GET /v1/wallet/withdraw/:id. Those require a signed-in session rather than an API key.

What you can withdraw

Only the prefunded USDC portion. Card credit is never withdrawable, and a withdrawal request cannot reach it.

If either ledger row is frozen, both are frozen — the balances are one funding decision, so a hold on one side stops spending from the other too. That is intentional, not a bug.

Auto top-up

Keep a floor under the balance rather than watching it:

Writes require billing.manage and are idempotent.

Related

• Payments overview — the funding options side by side
• Fiat payments — the card-credit ledger this one complements
• x402 — paying per request with no account at all