> For the complete documentation index, see [llms.txt](https://docs.sectoral.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sectoral.xyz/developer-api/accounts.md).

# 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: Sectoral's servers have no view into your balances, so decryption always happens on your end.

***

## Fetch your account

```
GET /v1/accounts/me
```

### Response

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

| Field        | Type     | Description                                              |
| ------------ | -------- | -------------------------------------------------------- |
| `account_id` | `string` | Sectoral's internal ID for the account                   |
| `handle`     | `string` | The `@handle` assigned to the account                    |
| `type`       | `string` | One of `personal`, `business` or `agent`                 |
| `public_key` | `string` | The account's Robinhood Chain address, beginning with 0x |
| `kyc_status` | `string` | One of `unverified`, `pending`, `verified` or `enhanced` |
| `created_at` | `string` | Creation time as an ISO 8601 timestamp                   |

***

## 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

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

### Response

```json
{
  "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

```json
{
  "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](/developer-api/agents.md).

***

## Error responses

| Status | Code                       | Description                                                            |
| ------ | -------------------------- | ---------------------------------------------------------------------- |
| `401`  | `unauthorized`             | No API key was sent, or the key is not valid                           |
| `403`  | `kyc_required`             | The account has not finished the identity verification this call needs |
| `422`  | `decryption_proof_invalid` | The proof doesn't match the ciphertext of the account's balance        |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.sectoral.xyz/developer-api/accounts.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.