Account and Balance Endpoints

These endpoints return profile details and balances for the account behind your API key. Privacy still applies when you are only reading data: Cyphron's servers have no view into your balances, so decryption always happens on your end.

Fetch your account

GET /v1/accounts/me

Response

{
  "account_id": "acct_8f2b1c",
  "handle": "@yourname",
  "type": "personal",
  "public_key": "0x8F2b1CxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxA9e",
  "kyc_status": "verified",
  "created_at": "2026-01-14T09:00:00Z"
}

Fetch balances

GET /v1/accounts/me/balances

You get one decrypted balance for each asset the account holds. Include a decryption proof generated on the client, since the servers are unable to decrypt balances on their own. That limitation comes from the cryptography itself, not from a policy you have to take on faith.

Request

{
  "decryption_proof": "base64-encoded proof generated client-side"
}

Response

{
  "balances": [
    { "asset": "USDG", "amount": "1245.30" },
    { "asset": "ETH", "amount": "0.0042" }
  ]
}

Without decryption_proof, the endpoint can only tell you whether each asset's balance is above zero. It returns no amount, because it cannot read the encrypted value.

List your agents

GET /v1/accounts/me/agents

Returns all agents that sit in the authenticated account's namespace, so you can see your entire fleet with a single request.

Response

{
  "agents": [
    {
      "account_id": "acct_9d3a2f",
      "handle": "@yourname/research-bot",
      "public_key": "0x9D3a2FxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxC4b",
      "status": "active",
      "spend_policy_id": "policy_4471"
    }
  ]
}

To create agents or manage their policies, see Agent and Policy Endpoints.

Error responses