Vault & Funding

Every agent credit line is backed by USDC you deposit into your vault. This page covers depositing, withdrawing (and the gates on withdrawal), and checking your balance — the operational side of collateral management for operators.

The vault in one minute

The vault is an ERC-4626 contract on Base. You deposit USDC and receive non-transferable vault shares that track your position. While your collateral sits in the vault it earns LP yield (the 3% LP slice of the 5% transaction fee is paid to vault depositors). The rule that drives everything else on this page: Vault balance = borrowing capacity. The sum of all your agents’ credit limits can never exceed what your vault collateral backs. Want a bigger or additional credit line? Deposit more. Want your USDC back? Unwind the credit drawn against it first. For share accounting, yield mechanics, and contract addresses, see ERC-4626 Vault. This page stays at the API level.

Deposit USDC

Depositing is a two-step flow: the API prepares the transaction, and you submit it on-chain from a wallet you control. POST /vault/deposit returns call_data for the deposit:

curl -X POST https://api-sandbox.sohopay.xyz/v1/vault/deposit \
  -H "Authorization: Bearer $SOHOPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: vault-deposit-2026-08-22-a" \
  -d '{
    "merchant_id": "mch_sandbox_demo",
    "amount": "1000.00"
  }'

import { SohoPay } from "@sohopay/sdk";

const sohopay = new SohoPay({ apiKey: process.env.SOHOPAY_API_KEY });

const deposit = await sohopay.vault.deposit({
  merchantId: "mch_sandbox_demo",
  amount: "1000.00",
});

console.log(deposit.to, deposit.callData);

from sohopay import SohoPay

sohopay = SohoPay(api_key=os.environ["SOHOPAY_API_KEY"])

deposit = sohopay.vault.deposit(
    merchant_id="mch_sandbox_demo",
    amount="1000.00",
)

print(deposit.to, deposit.call_data)

Response

{
  "vault_address": "0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b",
  "to": "0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b",
  "amount": "1000.00",
  "call_data": "0x6e553f65000000000000000000000000...",
  "chain_id": 84532
}

Submit the transaction from your operator wallet (approve USDC for the vault first if you haven’t). Once the deposit confirms on-chain — ~1s finality on Base — your borrowing capacity updates and new or larger credit lines can be created against it.

The API never takes custody of your deposit funds. It only builds the calldata; the transaction is signed and submitted by you, from your own wallet.

Withdraw USDC

Withdrawal follows the same prepare-then-submit shape via POST /vault/withdraw, but it is gated: you can only withdraw collateral that is not currently backing outstanding credit. While any agent carries a balance drawn against your vault, a withdrawal that would cut into that backing is rejected with 409 WITHDRAWAL_GATED:

409 WITHDRAWAL_GATED

{
  "error": {
    "code": "WITHDRAWAL_GATED",
    "message": "Withdrawal of 800.00 USDC exceeds withdrawable balance of 350.00 USDC while 650.00 USDC of credit is outstanding.",
    "request_id": "req_8e2f6c1d"
  }
}

To free up collateral, unwind credit first:

Pause agents so they stop drawing new credit.
Let outstanding balances settle and repay.
Lower or close credit lines you no longer need.
Check withdrawable (below), then withdraw up to that amount.

Check your balance

GET /vault/balance/{merchant_id} returns the three numbers that matter:

curl https://api-sandbox.sohopay.xyz/v1/vault/balance/mch_sandbox_demo \
  -H "Authorization: Bearer $SOHOPAY_API_KEY"

const balance = await sohopay.vault.balance("mch_sandbox_demo");
console.log(balance.vaultBalance, balance.creditInUse, balance.withdrawable);

balance = sohopay.vault.balance("mch_sandbox_demo")
print(balance.vault_balance, balance.credit_in_use, balance.withdrawable)

Response

{
  "merchant_id": "mch_sandbox_demo",
  "vault_balance": "1000.00",
  "credit_in_use": "650.00",
  "withdrawable": "350.00",
  "updated_at": "2026-08-22T11:42:07Z"
}

vault_balance — your total collateral (and total borrowing capacity).
credit_in_use — collateral currently backing outstanding agent balances.
withdrawable — what you can pull out right now: vault_balance - credit_in_use.

Poll this before withdrawals, and alert when withdrawable approaches zero — that means your agents are near fully leveraged against your collateral and new payments will start failing with INSUFFICIENT_CREDIT.

Sandbox

Sandbox accounts come pre-funded with test vault collateral on Base Sepolia, so you can create agents and settle payments without depositing anything. The deposit and withdraw endpoints still work in sandbox if you want to exercise the full flow with test USDC.

Next steps

ERC-4626 Vault

Share accounting, yield, and the contract itself.

Agent Setup

Create credit lines against your new collateral.

Payment Flow

Put the credit to work: orders, signing, settlement.

Getting Started

Merchant Integration

Agent Wallet Setup

Payment Flow

Protocol & Standards

Compliance & Risk

Operational Dashboards

Vault & Funding

The vault in one minute

Deposit USDC

Withdraw USDC

Check your balance

Sandbox

Next steps

ERC-4626 Vault

Agent Setup

Payment Flow

​The vault in one minute

​Deposit USDC

​Withdraw USDC

​Check your balance

​Sandbox

​Next steps

ERC-4626 Vault

Agent Setup

Payment Flow

The vault in one minute

Deposit USDC

Withdraw USDC

Check your balance

Sandbox

Next steps