Wallets

A wallet is a Safe multisig deployed on Base, owned by one or more signer addresses and governed by a signature threshold. It holds USDC (and ETH for gas), and it's the source of every payment.

Wallets are created with a predicted address immediately, then deployed on-chain asynchronously. Track deployment via status:

PENDING_DEPLOYMENT → DEPLOYING → DEPLOYED   (or → FAILED)

Key endpoints

Method	Path	Scope	Purpose
POST	/v1/wallets	wallets:write	Create a wallet.
GET	/v1/wallets	wallets:read	List wallets (paginated: skip, take).
GET	/v1/wallets/{id}	wallets:read	Get one wallet, with balances.
POST	/v1/wallets/{id}/fund	wallets:fund	Fund from the faucet (sandbox).

See the REST reference for the complete wallet surface, including on-chain transaction proposal (POST /v1/wallets/{id}/transactions) and the sign/execute routes.

Create a wallet

Provide a name and at least one owner. threshold defaults to 1; chainId defaults to the environment's chain (Base Sepolia 84532 in sandbox).

curl

curl -X POST https://api.sandbox.safebank.ai/v1/wallets \
  -H "X-SafeBank-Api-Key: $SAFEBANK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Treasury",
    "owners": [{ "address": "0xYourSigner", "role": "ADMIN_OWNER" }],
    "threshold": 1,
    "chainId": 84532
  }'

TypeScript

const wallet = await sb.wallets.create({
  name: 'Acme Treasury',
  owners: [{ address: '0xYourSigner', role: 'ADMIN_OWNER' }],
  threshold: 1,
})

// Optionally block until it's live on-chain:
const active = await sb.waitForWalletActive(wallet.id)

CLI

sb wallets create --name "Acme Treasury" --threshold 1 --wait

Owner role is one of ADMIN_OWNER, FINANCE_OWNER, MERCHANT_OPERATOR, or AGENT. The response is a Wallet:

{
  "id": "w_1a2b3c",
  "address": "0x7Fb2…c41A",
  "status": "PENDING_DEPLOYMENT",
  "chainId": 84532,
  "threshold": 1,
  "predictedAddress": true,
  "name": "Acme Treasury",
  "owners": [{ "address": "0xYourSigner", "role": "ADMIN_OWNER", "label": null }],
  "createdAt": "2026-08-09T12:00:00.000Z"
}

predictedAddress: true means the address is the deterministic counterfactual Safe address — it's stable and safe to fund before deployment completes.

List and inspect

TypeScript

const { wallets, total } = await sb.wallets.list({ take: 20 })
const one = await sb.wallets.get('w_1a2b3c') // includes `balances`
for (const b of one.balances ?? []) console.log(b.asset, b.amount)

curl

curl "https://api.sandbox.safebank.ai/v1/wallets?take=20" \
  -H "X-SafeBank-Api-Key: $SAFEBANK_API_KEY"

curl https://api.sandbox.safebank.ai/v1/wallets/w_1a2b3c \
  -H "X-SafeBank-Api-Key: $SAFEBANK_API_KEY"

CLI

sb wallets list
sb wallets get w_1a2b3c   # shows balances

GET /v1/wallets/{id} includes a balances array ({ asset, amount, decimals }).

Next

• Fund a wallet from the sandbox faucet.
• Send a payment from a funded wallet.