Create Wallet - Naïve

POST

users

:user_id

wallet

curl -X POST https://api.usenaive.ai/v1/users/user-uuid-1/wallet \
  -H "Authorization: Bearer nv_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "custody": "cdp",
    "networks": ["eip155:8453"],
    "policy": { "perTxMax": "1.00", "dailyBudget": "10.00" }
  }'

{
  "id": "wallet-uuid-1",
  "companyId": "company-uuid-1",
  "tenantUserId": "user-uuid-1",
  "network": "eip155:8453",
  "address": "0xa1b2c3d4e5f60718293a4b5c6d7e8f9012345678",
  "custody": "cdp",
  "providerRef": "company-uuid-1:user-uuid-1",
  "policyJson": {
    "perTxMax": "1.00",
    "dailyBudget": "10.00"
  },
  "cdpPolicyId": "pol_9f3c1a",
  "status": "active",
  "createdAt": "2026-07-01T10:00:00Z",
  "updatedAt": "2026-07-01T10:00:00Z"
}

Provisions the agent’s wallet in the custody plane and persists it. Idempotent — if the agent already has a wallet, the existing one is returned unchanged and no new wallet is created.

Operator only. Provisioning requires an operator credential: a signed-in dashboard session, or an API key minted with the wallet:admin scope. An agent key is refused with 403 (reason: wallet_admin_requires_operator).create, fund, transfer, policy and sweep are the operator surface. An agent spends from its wallet via Pay — it cannot administer it.

Request Body

Parameter	Type	Required	Description
`custody`	string	No	`cdp` \| `local` \| `fake`. Defaults to the configured wallet provider (`fake` unless CDP is enabled)
`networks`	string[]	No	CAIP-2 networks; the first becomes the wallet’s network. Defaults to `["eip155:8453"]`
`policy`	object	No	Spend policy — `perTxMax` (decimal USDC), optional `dailyBudget`, optional `lowBalanceThreshold`. Defaults to `{ "perTxMax": "0.50" }`
`smartAccount`	boolean	No	Provision as a smart account

curl -X POST https://api.usenaive.ai/v1/users/user-uuid-1/wallet \
  -H "Authorization: Bearer nv_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "custody": "cdp",
    "networks": ["eip155:8453"],
    "policy": { "perTxMax": "1.00", "dailyBudget": "10.00" }
  }'

{
  "id": "wallet-uuid-1",
  "companyId": "company-uuid-1",
  "tenantUserId": "user-uuid-1",
  "network": "eip155:8453",
  "address": "0xa1b2c3d4e5f60718293a4b5c6d7e8f9012345678",
  "custody": "cdp",
  "providerRef": "company-uuid-1:user-uuid-1",
  "policyJson": {
    "perTxMax": "1.00",
    "dailyBudget": "10.00"
  },
  "cdpPolicyId": "pol_9f3c1a",
  "status": "active",
  "createdAt": "2026-07-01T10:00:00Z",
  "updatedAt": "2026-07-01T10:00:00Z"
}

Fail-closed provisioning

perTxMax is written into the custody plane as a static account policy at create time, which is what makes it survive a compromised agent runtime. If that policy cannot be attached, provisioning fails with 500 internal_error and no wallet is created — there is never a wallet without its cap. Retry the call. Likewise, if the custody backend is unconfigured (BYO CDP credentials absent), the call fails with wallet_not_configured before any row is written.

Errors

Status	Code	When
400	`wallet_not_configured`	No CDP account connected. Connect one (BYO credentials) to enable crypto wallets
403	`forbidden`	The Account Kit has not enabled `payments`, or the caller is not an operator (`wallet_admin_requires_operator`)
500	`internal_error`	The spend policy could not be attached; no wallet was created. Retry

CLI

naive use <user-id>
naive wallet create

With an explicit custody backend and policy:

naive wallet create --custody cdp --network eip155:8453 \
  --per-tx-max 1.00 --daily-budget 10.00

This is an operator command — it goes through a signed-in human session. Start one with naive auth session-login, or naive auth google / naive auth email <email> in the browser.

MCP

No MCP tool — deliberately. Wallet provisioning is the operator surface and is not exposed to agents. A wallet an agent can’t reach is the cheapest policy of all.

curl -X POST https://api.usenaive.ai/v1/users/user-uuid-1/wallet \
  -H "Authorization: Bearer nv_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "custody": "cdp",
    "networks": ["eip155:8453"],
    "policy": { "perTxMax": "1.00", "dailyBudget": "10.00" }
  }'

{
  "id": "wallet-uuid-1",
  "companyId": "company-uuid-1",
  "tenantUserId": "user-uuid-1",
  "network": "eip155:8453",
  "address": "0xa1b2c3d4e5f60718293a4b5c6d7e8f9012345678",
  "custody": "cdp",
  "providerRef": "company-uuid-1:user-uuid-1",
  "policyJson": {
    "perTxMax": "1.00",
    "dailyBudget": "10.00"
  },
  "cdpPolicyId": "pol_9f3c1a",
  "status": "active",
  "createdAt": "2026-07-01T10:00:00Z",
  "updatedAt": "2026-07-01T10:00:00Z"
}

​Request Body

​Fail-closed provisioning

​Errors

​CLI

​MCP

Request Body

Fail-closed provisioning

Errors

CLI

MCP