> For the complete documentation index, see [llms.txt](https://docs.cheqd.io/product/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cheqd.io/product/api-reference/combined/account.md).

# Account

## Fetch custodian-mode client details.

> This endpoint returns the custodian-mode client details for authenticated users.

```json
{"openapi":"3.0.0","info":{"title":"cheqd Studio API for cheqd network","version":"2.0.0"},"tags":[{"name":"Account"}],"servers":[{"url":"https://studio-api.cheqd.net","description":"Main (production) server"},{"url":"https://studio-api-staging.cheqd.net","description":"Staging server for testing"},{"url":"http://localhost:3000","description":"Local server for testing"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"x-api-key","in":"header"}},"schemas":{"Customer":{"type":"object","properties":{"customer":{"type":"object","properties":{"customerId":{"type":"string"},"name":{"type":"string"}}},"paymentAccount":{"type":"object","properties":{"mainnet":{"type":"string"},"testnet":{"type":"string"}}}}},"InvalidRequest":{"description":"A problem with the input fields has occurred. Additional state information plus metadata may be available in the response body.","type":"object","properties":{"error":{"type":"string"}}},"UnauthorizedError":{"description":"Access token is missing or invalid","type":"object","properties":{"error":{"type":"string"}}},"InternalError":{"description":"An internal error has occurred. Additional state information plus metadata may be available in the response body.","type":"object","properties":{"error":{"type":"string"}}}}},"paths":{"/account":{"get":{"tags":["Account"],"summary":"Fetch custodian-mode client details.","description":"This endpoint returns the custodian-mode client details for authenticated users.","responses":{"200":{"description":"The request was successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Customer"}}}},"400":{"$ref":"#/components/schemas/InvalidRequest"},"401":{"$ref":"#/components/schemas/UnauthorizedError"},"500":{"$ref":"#/components/schemas/InternalError"}}}}}}
```

## Fetch IdToken.

> This endpoint returns IdToken as JWT with list of user roles inside

```json
{"openapi":"3.0.0","info":{"title":"cheqd Studio API for cheqd network","version":"2.0.0"},"tags":[{"name":"Account"}],"servers":[{"url":"https://studio-api.cheqd.net","description":"Main (production) server"},{"url":"https://studio-api-staging.cheqd.net","description":"Staging server for testing"},{"url":"http://localhost:3000","description":"Local server for testing"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"x-api-key","in":"header"}},"schemas":{"QueryIdTokenResponseBody":{"type":"object","properties":{"idToken":{"type":"string"}}},"InvalidRequest":{"description":"A problem with the input fields has occurred. Additional state information plus metadata may be available in the response body.","type":"object","properties":{"error":{"type":"string"}}},"UnauthorizedError":{"description":"Access token is missing or invalid","type":"object","properties":{"error":{"type":"string"}}},"InternalError":{"description":"An internal error has occurred. Additional state information plus metadata may be available in the response body.","type":"object","properties":{"error":{"type":"string"}}}}},"paths":{"/account/idtoken":{"get":{"tags":["Account"],"summary":"Fetch IdToken.","description":"This endpoint returns IdToken as JWT with list of user roles inside","deprecated":true,"responses":{"200":{"description":"The request was successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryIdTokenResponseBody"}}}},"400":{"$ref":"#/components/schemas/InvalidRequest"},"401":{"$ref":"#/components/schemas/UnauthorizedError"},"500":{"$ref":"#/components/schemas/InternalError"}}}}}}
```

## Create an client for an authenticated user.

> This endpoint creates a client in the custodian-mode for an authenticated user

```json
{"openapi":"3.0.0","info":{"title":"cheqd Studio API for cheqd network","version":"2.0.0"},"tags":[{"name":"Account"}],"servers":[{"url":"https://studio-api.cheqd.net","description":"Main (production) server"},{"url":"https://studio-api-staging.cheqd.net","description":"Staging server for testing"},{"url":"http://localhost:3000","description":"Local server for testing"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"x-api-key","in":"header"}},"schemas":{"AccountCreateRequest":{"type":"object","required":["primaryEmail"],"properties":{"name":{"type":"string"},"primaryEmail":{"type":"string"}}},"AccountCreateResponse":{"type":"object","properties":{"customerId":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"description":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"paymentProviderId":{"type":"string"}}},"InvalidRequest":{"description":"A problem with the input fields has occurred. Additional state information plus metadata may be available in the response body.","type":"object","properties":{"error":{"type":"string"}}},"UnauthorizedError":{"description":"Access token is missing or invalid","type":"object","properties":{"error":{"type":"string"}}},"InternalError":{"description":"An internal error has occurred. Additional state information plus metadata may be available in the response body.","type":"object","properties":{"error":{"type":"string"}}}}},"paths":{"/account/create":{"post":{"tags":["Account"],"summary":"Create an client for an authenticated user.","description":"This endpoint creates a client in the custodian-mode for an authenticated user","requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/AccountCreateRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/AccountCreateRequest"}}}},"responses":{"201":{"description":"The request was successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountCreateResponse"}}}},"400":{"$ref":"#/components/schemas/InvalidRequest"},"401":{"$ref":"#/components/schemas/UnauthorizedError"},"500":{"$ref":"#/components/schemas/InternalError"}}}}}}
```

## Request cheqd testnet CHEQ tokens for a Studio payment account.

> Funds a cheqd testnet address, by default the customer's own payment account, or any valid cheqd address supplied. An address can hold at most FAUCET\_ADDRESS\_CAP\_CHEQ, and a customer can request at most FAUCET\_MONTHLY\_LIMIT\_CHEQ per calendar month (UTC) across all their addresses; both default to 100,000 CHEQ. Without an amount, FAUCET\_DEFAULT\_REQUEST\_CHEQ (default 10,000 CHEQ) is sent, or less if the room under the address cap or the quota left is lower. Authentication is by a Studio user session (bearer token), an API key (\`x-api-key\`) or a machine-to-machine token (bearer token plus a \`customer-id\` header); whichever is used, the credential must carry the \`request:faucet:testnet\` scope. The response includes the remaining quota.

```json
{"openapi":"3.0.0","info":{"title":"cheqd Studio API for cheqd network","version":"2.0.0"},"tags":[{"name":"Account"}],"servers":[{"url":"https://studio-api.cheqd.net","description":"Main (production) server"},{"url":"https://studio-api-staging.cheqd.net","description":"Staging server for testing"},{"url":"http://localhost:3000","description":"Local server for testing"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"x-api-key","in":"header"}},"schemas":{"InvalidRequest":{"description":"A problem with the input fields has occurred. Additional state information plus metadata may be available in the response body.","type":"object","properties":{"error":{"type":"string"}}},"UnauthorizedError":{"description":"Access token is missing or invalid","type":"object","properties":{"error":{"type":"string"}}},"InternalError":{"description":"An internal error has occurred. Additional state information plus metadata may be available in the response body.","type":"object","properties":{"error":{"type":"string"}}}}},"paths":{"/account/faucet":{"post":{"tags":["Account"],"summary":"Request cheqd testnet CHEQ tokens for a Studio payment account.","description":"Funds a cheqd testnet address, by default the customer's own payment account, or any valid cheqd address supplied. An address can hold at most FAUCET_ADDRESS_CAP_CHEQ, and a customer can request at most FAUCET_MONTHLY_LIMIT_CHEQ per calendar month (UTC) across all their addresses; both default to 100,000 CHEQ. Without an amount, FAUCET_DEFAULT_REQUEST_CHEQ (default 10,000 CHEQ) is sent, or less if the room under the address cap or the quota left is lower. Authentication is by a Studio user session (bearer token), an API key (`x-api-key`) or a machine-to-machine token (bearer token plus a `customer-id` header); whichever is used, the credential must carry the `request:faucet:testnet` scope. The response includes the remaining quota.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string","description":"Optional cheqd testnet address to fund; it does not have to belong to the customer. Requests count against the calling customer's quota. Defaults to the authenticated customer's testnet account."},"amount":{"type":"number","description":"Optional amount in CHEQ. If omitted, FAUCET_DEFAULT_REQUEST_CHEQ (default 10,000) is sent, or less if the room under the address cap or the monthly quota left is lower. Set it to ask for more; the response shows the amount sent."}}}}}},"responses":{"200":{"description":"The request was processed."},"400":{"$ref":"#/components/schemas/InvalidRequest"},"401":{"$ref":"#/components/schemas/UnauthorizedError"},"403":{"description":"Forbidden."},"404":{"description":"No Studio testnet payment account was found for this customer."},"429":{"description":"Too many requests. Either the customer's monthly faucet quota is exhausted (the body includes the quota details), or a request was made too soon after the previous one (FAUCET_MIN_INTERVAL_SECONDS). The Retry-After header gives the seconds to wait."},"500":{"$ref":"#/components/schemas/InternalError"},"502":{"description":"Upstream faucet request failed."},"503":{"description":"Stripe subscription checks are disabled."},"504":{"description":"The faucet did not respond within FAUCET_REQUEST_TIMEOUT_SECONDS. The request may or may not have been processed."}}}}}}
```

## Fetch Account Analytics.

> This endpoint returns analytics data for the account usage.

```json
{"openapi":"3.0.0","info":{"title":"cheqd Studio API for cheqd network","version":"2.0.0"},"tags":[{"name":"Account"}],"servers":[{"url":"https://studio-api.cheqd.net","description":"Main (production) server"},{"url":"https://studio-api-staging.cheqd.net","description":"Staging server for testing"},{"url":"http://localhost:3000","description":"Local server for testing"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"x-api-key","in":"header"}},"schemas":{"AccountAnalyticsResponse":{"type":"object","properties":{"dids":{"type":"integer"},"credentials":{"type":"integer"},"accreditations":{"type":"integer"},"resources":{"type":"integer"}}},"InvalidRequest":{"description":"A problem with the input fields has occurred. Additional state information plus metadata may be available in the response body.","type":"object","properties":{"error":{"type":"string"}}},"UnauthorizedError":{"description":"Access token is missing or invalid","type":"object","properties":{"error":{"type":"string"}}},"InternalError":{"description":"An internal error has occurred. Additional state information plus metadata may be available in the response body.","type":"object","properties":{"error":{"type":"string"}}}}},"paths":{"/account/analytics":{"get":{"tags":["Account"],"summary":"Fetch Account Analytics.","description":"This endpoint returns analytics data for the account usage.","parameters":[{"in":"query","name":"network","description":"Filter DID by the network published.","schema":{"type":"string","enum":["mainnet","testnet"]}}],"responses":{"200":{"description":"The request was successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountAnalyticsResponse"}}}},"400":{"$ref":"#/components/schemas/InvalidRequest"},"401":{"$ref":"#/components/schemas/UnauthorizedError"},"500":{"$ref":"#/components/schemas/InternalError"}}}}}}
```

## Fetch payment account balances.

> Returns the on-chain balance of the authenticated customer's mainnet and testnet payment accounts, expressed in ncheq, CHEQ and USD. The CHEQ/USD rate is sourced from CoinGecko and cached; if it (or a network's RPC endpoint) is unavailable the response still returns 200 with the affected \`usd\`/\`rate\`/\`balance\` fields set to \`null\`. Also returns the testnet faucet cap and the customer's monthly faucet quota usage under \`faucet\`.

```json
{"openapi":"3.0.0","info":{"title":"cheqd Studio API for cheqd network","version":"2.0.0"},"tags":[{"name":"Account"}],"servers":[{"url":"https://studio-api.cheqd.net","description":"Main (production) server"},{"url":"https://studio-api-staging.cheqd.net","description":"Staging server for testing"},{"url":"http://localhost:3000","description":"Local server for testing"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"x-api-key","in":"header"}},"schemas":{"AccountBalancesResponse":{"type":"object","properties":{"mainnet":{"$ref":"#/components/schemas/AccountNetworkBalance"},"testnet":{"$ref":"#/components/schemas/AccountNetworkBalance"},"faucet":{"type":"object","nullable":true,"description":"Testnet faucet cap and the customer's monthly faucet quota usage. `null` when there is no testnet account or it could not be read.","properties":{"cap":{"type":"object","description":"Most CHEQ a testnet address can hold before the faucet stops topping it up.","properties":{"cheq":{"type":"number"},"ncheq":{"type":"string"}}},"quota":{"type":"object","properties":{"period":{"type":"string"},"limit":{"$ref":"#/components/schemas/FaucetAmount"},"used":{"$ref":"#/components/schemas/FaucetAmount"},"remaining":{"$ref":"#/components/schemas/FaucetAmount"},"resetsAt":{"type":"string","format":"date-time"}}}}},"rate":{"type":"object","nullable":true,"description":"CHEQ/USD spot rate used for the `usd` fields. `null` when it could not be fetched.","properties":{"cheqUsd":{"type":"number"},"source":{"type":"string"},"asOf":{"type":"string","format":"date-time"}}}}},"AccountNetworkBalance":{"type":"object","nullable":true,"description":"Balance of a single payment account. `null` when the customer has no account on that network.","properties":{"address":{"type":"string"},"denom":{"type":"string"},"balance":{"type":"object","nullable":true,"description":"On-chain balance. `null` when the network's RPC query failed.","properties":{"ncheq":{"type":"string"},"cheq":{"type":"number"}}},"usd":{"type":"number","nullable":true,"description":"balance.cheq multiplied by the CHEQ/USD rate. `null` when the balance or the rate is unavailable."}}},"FaucetAmount":{"type":"object","properties":{"cheq":{"type":"number"},"ncheq":{"type":"string"}}},"UnauthorizedError":{"description":"Access token is missing or invalid","type":"object","properties":{"error":{"type":"string"}}},"InternalError":{"description":"An internal error has occurred. Additional state information plus metadata may be available in the response body.","type":"object","properties":{"error":{"type":"string"}}}}},"paths":{"/account/balances":{"get":{"tags":["Account"],"summary":"Fetch payment account balances.","description":"Returns the on-chain balance of the authenticated customer's mainnet and testnet payment accounts, expressed in ncheq, CHEQ and USD. The CHEQ/USD rate is sourced from CoinGecko and cached; if it (or a network's RPC endpoint) is unavailable the response still returns 200 with the affected `usd`/`rate`/`balance` fields set to `null`. Also returns the testnet faucet cap and the customer's monthly faucet quota usage under `faucet`.","responses":{"200":{"description":"The request was successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountBalancesResponse"}}}},"401":{"$ref":"#/components/schemas/UnauthorizedError"},"500":{"$ref":"#/components/schemas/InternalError"}}}}}}
```


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.cheqd.io/product/api-reference/combined/account.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.