Vaults API

Vaults are on-chain smart-contract wallets that hold USDC funds. Each vault is owned by a single wallet address and deployed on a specific chain. Agents are authorized to spend from vaults according to their assigned policies.

Create Vault#

POST

/v1/vaults

Create a new vault on the specified chain.

Request Body#

| Field | Type | Required | Description | |---|---|---|---| | owner_wallet | string | Yes | The wallet address that owns this vault | | chain | string | Yes | Blockchain to deploy on: "solana" or "base" | | label | string | No | Human-readable label for the vault |

Example Request#

{
  "owner_wallet": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
  "chain": "solana",
  "label": "Production Vault"
}

Response#

{
  "vault_id": "550e8400-e29b-41d4-a716-446655440000",
  "vault_address": "vault_a1b2c3d4e5f6...",
  "owner_wallet": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
  "chain": "solana",
  "balance": "0.000000",
  "status": "active",
  "created_at": "2025-01-15T10:30:00.000Z"
}

Errors#

| Error Code | Description | |---|---| | chain_error | Failed to deploy the vault on-chain | | internal_error | Unexpected server error |

Get Vault#

GET

/v1/vaults/:id

Retrieve details of a specific vault.

Path Parameters#

| Parameter | Type | Description | |---|---|---| | id | string | The vault ID (UUID) |

Response#

{
  "vault_id": "550e8400-e29b-41d4-a716-446655440000",
  "vault_address": "vault_a1b2c3d4e5f6...",
  "owner_wallet": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
  "chain": "solana",
  "balance": "1250.500000",
  "status": "active",
  "authorized_agents": [],
  "created_at": "2025-01-15T10:30:00.000Z"
}

Errors#

| Error Code | Description | |---|---| | vault_not_found | No vault exists with the given ID |

Freeze Vault#

POST

/v1/vaults/:id/freeze

Freeze a vault, preventing all transactions.

Freezing a vault immediately blocks all payment requests and escrow operations. Agents authorized on the vault will receive vault_frozen errors. This is an emergency action that takes effect instantly.

Path Parameters#

| Parameter | Type | Description | |---|---|---| | id | string | The vault ID (UUID) |

Response#

{
  "vault_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "frozen",
  "frozen_at": "2025-01-15T14:22:00.000Z"
}

Errors#

| Error Code | Description | |---|---| | vault_not_found | No vault exists with the given ID |

Freezing a vault blocks all agent activity immediately. Pending approval requests will not be processable until the vault is unfrozen.

Unfreeze Vault#

POST

/v1/vaults/:id/unfreeze

Unfreeze a previously frozen vault.

Restores normal operation. Agents can resume making payments once unfrozen.

Path Parameters#

| Parameter | Type | Description | |---|---|---| | id | string | The vault ID (UUID) |

Response#

{
  "vault_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "active",
  "unfrozen_at": "2025-01-15T15:00:00.000Z"
}

Errors#

| Error Code | Description | |---|---| | vault_not_found | No vault exists with the given ID | | invalid_state | Vault is not currently frozen |