Vaults API

Deploy and manage the multisig smart-contract vaults that back each card. See Vaults concepts.

API v1 · Legacy

This page is part of the reference of the first version of the Web3Card API, kept here for reference. API v1 does not take new integrations: API v2 replaces it, and the platform today works as described in the rest of this manual.

POST /vaults

Deploy a vault for a KYC-approved user.

// Request
{ "userId": "usr_9f4c", "chain": "polygon", "currency": "USDC" }

// Response
{
  "id": "vlt_77aa",
  "userId": "usr_9f4c",
  "chain": "polygon",
  "currency": "USDC",
  "address": null,
  "status": "deploying",
  "createdAt": "2026-07-19T14:00:00Z"
}

Deployment is asynchronous. The vault becomes active when the contract is live, and the address field is populated. A vault.deployed webhook is emitted.

GET /vaults/{id}

Retrieve a vault, its address, status, and available balance.

// Response
{
  "id": "vlt_77aa",
  "userId": "usr_9f4c",
  "chain": "polygon",
  "currency": "USDC",
  "address": "0x8247E5a9c11b36c1d19D4a2e9Eb0cE3606eB48a3",
  "balance": "487.35",
  "status": "active"
}

balance is the spendable amount: on-chain balance minus pending authorization holds.

GET /vaults

List vaults. Filters: userId, chain, status.

GET /vaults/{id}/owners

List the vault's owner wallets.

POST /vaults/{id}/owners

Add an owner wallet. Requires a user session; returns EIP-712 typed data for the current owner to sign.

DELETE /vaults/{id}/owners/{address}

Remove an owner wallet. Requires a user session and owner signature.

POST /vaults/{id}/withdrawals

Prepare a withdrawal from the vault to the owner's wallet. Returns the transaction data for the owner to sign and submit with their own wallet.

// Request
{ "amount": "200.00", "to": "0x71C2a4f3b7c48d19D4a2e9Eb0cE3606eB48a3a4F" }

// Response
{
  "to": "0x8247E5a9c11b36c1d19D4a2e9Eb0cE3606eB48a3",
  "data": "0xa9059cbb…",
  "value": "0",
  "chainId": 137
}

Withdrawals never require platform approval: the vault owner can always exit with their funds.