Wallets API
Manage stablecoin wallets for agent payments.
Authentication
All endpoints require either:
- Session auth (browser login cookie)
- Org API key:
Authorization: Bearer conto_xxx...
List Wallets
curl https://conto.finance/api/wallets \
-H "Authorization: Bearer $CONTO_API_KEY"
Query Parameters
| Parameter | Type | Description |
|---|
status | string | Filter: ACTIVE, FROZEN, CLOSED |
chainType | string | Filter: EVM, SOLANA |
chainId | string | Filter by chain ID |
Response
{
"wallets": [
{
"id": "cmm59z8fj000m49h7bjqza22q",
"name": "Operations Wallet",
"address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2e3a1",
"walletType": "EOA",
"chainType": "EVM",
"chainId": "42431",
"custodyType": "SPONGE",
"usdcBalance": 5000.00,
"status": "ACTIVE",
"isWatchOnly": false,
"createdAt": "2024-01-15T10:00:00Z"
}
]
}
Get Wallet
curl https://conto.finance/api/wallets/{walletId} \
-H "Authorization: Bearer $CONTO_API_KEY"
Create Wallet
curl -X POST https://conto.finance/api/wallets \
-H "Authorization: Bearer $CONTO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Operations Wallet",
"custodyType": "SPONGE",
"chainType": "EVM",
"chainId": "42431"
}'
Request Body
| Field | Type | Required | Default | Description |
|---|
name | string | Yes | - | Wallet display name (1-100 chars) |
walletType | string | No | EOA | EOA, SMART_WALLET, MULTISIG |
chainType | string | No | EVM | EVM or SOLANA |
chainId | string | No | - | Chain ID (e.g. "42431" for Tempo, "8453" for Base) |
custodyType | string | No | SPONGE | Custody provider (see below) |
importAddress | string | No | - | Import an existing wallet address |
isWatchOnly | boolean | No | false | Watch-only wallets cannot send transactions |
Custody Providers
| Provider | Description |
|---|
SPONGE | (Default) Fast setup with gas sponsorship for stablecoin transfers |
PRIVY | Enterprise-grade key management via Privy API with built-in policy controls |
EXTERNAL | Externally managed wallet (import address required) |
SMART_CONTRACT | (Coming Soon) On-chain enforcement via allowlist contract |
After creating a wallet, you must provision it to get a blockchain address. See the Provision endpoint below.
Provision Wallet
Provision a Sponge-custodied wallet on-chain. This links the wallet to the platform Sponge account, syncs a real blockchain address and balance, and marks the wallet ready for SDK-initiated payments.
No request body required.
curl -X POST https://conto.finance/api/wallets/{walletId}/provision \
-H "Authorization: Bearer $CONTO_API_KEY"
Response
{
"wallet": {
"id": "cmm...",
"name": "Operations Wallet",
"address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2e3a1",
"walletType": "EOA",
"chainType": "EVM",
"custodyType": "SPONGE",
"usdcBalance": 100.00,
"status": "ACTIVE"
},
"provisioned": true,
"chain": {
"name": "Tempo Testnet",
"chainId": "42431",
"explorer": "https://testnet.tempothroughput.com"
}
}
Update Wallet
curl -X PATCH https://conto.finance/api/wallets/{walletId} \
-H "Authorization: Bearer $CONTO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Updated Wallet Name",
"status": "FROZEN"
}'
Request Body
| Field | Type | Description |
|---|
name | string | Wallet display name (1-100 chars) |
status | string | ACTIVE, FROZEN, CLOSED |
Wallet Status Values
| Status | Description |
|---|
ACTIVE | Normal operation |
FROZEN | Temporarily disabled |
CLOSED | No longer in use |
Wallet Lifecycle
The recommended workflow for wallet setup:
- Create wallet via
POST /api/wallets
- Provision wallet via
POST /api/wallets/{id}/provision
- Link wallet to agent via
POST /api/agents/{agentId}/wallets
- Agent can now request payments using the wallet
Error Responses
| Status | Description |
|---|
| 400 | Invalid request data |
| 401 | Authentication failed |
| 403 | Missing required scope |
| 404 | Wallet not found |
| 409 | Wallet is frozen |
