Vault & Funding

​

The vault architecture in one minute

​

Key principles

1. Vault balance = borrowing capacity: The sum of all active agent credit lines provisioned under your account cannot exceed what your vault collateral backs.
2. Earn LP yield: While your collateral sits in the vault, it earns passive yield. The 3% LP slice of the 5% transaction fee is distributed directly to vault depositors.
3. Non-custodial design: The SohoPay API never holds or takes custody of your funds. The API prepares the transaction calldata, and you sign and broadcast the deposit from your own wallet.

​

Supported networks & USDC contracts

​

Deposit USDC collateral

​

Step 1: Prepare the deposit calldata

curl -X POST https://staging.api.sohopay.xyz/api/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,
  baseUrl: "https://staging.api.sohopay.xyz/api/v1",
});

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

console.log("Deposit target:", deposit.to, deposit.callData);

import os
from sohopay import SohoPay

sohopay = SohoPay(
    api_key=os.environ["SOHOPAY_API_KEY"],
    base_url="https://staging.api.sohopay.xyz/api/v1",
)

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

print("Deposit target:", deposit.to, deposit.call_data)

​

Response (200 OK):

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

​

Step 2: Broadcast on-chain

​

Withdraw USDC & gating rules

​

Gated withdrawal error (409 Conflict)

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

​

How to unwind collateral before withdrawal:

1. Pause active agents: Call POST /api/v1/agents/{id}/pause to prevent new payments from drawing on credit.
2. Settle balances: Allow in-flight orders to finalize and execute repayment.
3. Check withdrawable funds: Verify that withdrawable equals the desired amount.
4. Initiate withdrawal: Submit the withdrawal transaction.

​

Check vault balance & health

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

const balance = await sohopay.vault.balance("mch_sandbox_demo");
console.log(
  `Vault: ${balance.vaultBalance} | In Use: ${balance.creditInUse} | Available: ${balance.withdrawable}`
);

balance = sohopay.vault.balance("mch_sandbox_demo")
print(f"Vault: {balance.vault_balance} | In Use: {balance.credit_in_use} | Available: {balance.withdrawable}")

​

Response (200 OK):

{
  "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 — Total collateral deposited (sets total credit ceiling).
• credit_in_use — Amount actively backing outstanding agent balances.
• withdrawable — Collateral free to be withdrawn immediately (vault_balance - credit_in_use).

​

Sandbox testing

1. Claim test USDC from faucet.circle.com on Base Sepolia.
2. Run POST /api/v1/vault/deposit with your test key.
3. Submit the deposit transaction on Base Sepolia.

​

Next steps