get_account
Read account sections at task start or when the purchase reference is lost.
POST https://api.envoy.money/tools/get_account
Read account sections at task start or when the purchase reference is lost. Defaults to balance, services, active_purchase and held_purchases (money in open agent purchases, separate from held by the bank). Add profile for the user's name, verified mobile and email, or addresses for saved delivery addresses to fill checkout forms. Never returns card details.
| Title | Service | Read only | Destructive | Idempotent | External sites |
|---|---|---|---|---|---|
| Read account | shared | true | false | true | false |
Send a Central Auth bearer with agent scope. A key-bound connection also sends Envoy-Installation-Proof over this exact request. JSON bodies are limited to 64 KB; a larger body returns HTTP 413 with INVALID_INPUT.
Input
| Field | Required | Type | Description and rules |
|---|---|---|---|
include | No | array of "balance" | "limits" | "services" | "active_purchase" | "agent" | "profile" | "addresses" | "held_purchases" | Sections to read. A single string is also accepted. unique items; default ["balance","services","active_purchase","held_purchases"] |
Unknown fields are rejected. The exact input schema is on the schemas page.
Synthetic request
{}Success data
Every reply uses the shared envelope: ok, the purchase, next, user_action and error. Follow next; outputs may gain fields, so ignore ones you do not recognize.
This tool returns its payload in data:
Field in data | Required | Type | Description and rules |
|---|---|---|---|
account | Yes | object | Selected account sections. Balance and limit fields reuse the verified v1 read adapter; services lists registry identifiers. Absent sections were not requested. |
account.currency | No | string or null | Account currency. |
account.balance | No | object or null | — |
account.held | No | object or null | — |
account.spendable | No | object or null | — |
account.held_purchases | No | object or null | Open agent purchase card money, separate from the account held figure. |
account.limits_reserved | No | "not_reserved" | Limits are informational, not reserved or a promise of payment approval. |
account.unavailable | No | array of "balance" | "holds" | "spendable" | "currency" | "limits" | "profile" | "addresses" | "active_purchase" | — |
account.profile | No | object | Contact details for delivery and checkout forms. A null value has no source. |
account.addresses | No | array of object | Saved delivery addresses from the Envoy app, default first. Complete list: a partial list is reported unavailable. |
account.limits | No | array of object | — |
account.services | No | array of "purchase" | unique items |
account.active_purchase | No | object or null | V2.1 snapshot. Envelope validation enforces state invariants; the adapter separately enforces ownership and authoritative money evidence. |
account.agent | No | object | — |
Synthetic result
Example synthetic-compatible-payload (synthetic data):
{
"ok": true,
"contract": "envoy@2026-10",
"tool": "get_account",
"request_id": "req_synthetic",
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"server_time": "2026-09-29T12:00:00Z",
"replayed": false,
"purchase": null,
"data": {
"account": {
"currency": "INR",
"balance": {
"minor": 500000,
"currency": "INR",
"display": "₹5,000.00"
},
"held": {
"minor": 0,
"currency": "INR",
"display": "₹0.00"
},
"spendable": {
"minor": 500000,
"currency": "INR",
"display": "₹5,000.00"
},
"services": [
"purchase"
],
"active_purchase": null,
"unavailable": []
}
},
"next": {
"action": "continue",
"tool": null,
"args": null,
"instruction": "Envoy needs nothing more. Carry on with the user's task.",
"after_seconds": null,
"by": null
},
"user_action": null,
"follow_ups": [],
"error": null
}Errors
A failure has ok: false, changes nothing, and carries error plus one next. Branch on error.code and next, not on the HTTP status. The contract declares every code below for every tool; which one a call returns depends on the request and the purchase state.
| Code | HTTP status | Meaning | What the agent does |
|---|---|---|---|
INVALID_INPUT | 400 | Fix the supplied input. | Fix every field listed in error.fields, then call the same tool once more. |
UNAUTHENTICATED | 401 | Reconnect through Central Auth. | Ask the user to reconnect Envoy, then retry this call. |
NOT_ALLOWED | 403 | The operation is not allowed. | This connection may not do that. Tell the user; do not retry. |
SERVICE_NOT_ENABLED | 403 | The service is not enabled. | This Envoy service is not enabled for the user. Tell the user; do not retry. |
NOT_FOUND | 404 | Purchase absent or owned by another user. | No purchase matches that reference. Check the purchase id from this task; do not start a new purchase to recover. |
IDEMPOTENCY_CONFLICT | 409 | The same key has different input. | Retry with the original inputs unchanged, or use a new idempotency_key only for a genuinely new purchase. |
ACTIVE_PURCHASE_EXISTS | 409 | An active purchase already exists. | Another purchase is in progress. Show the user the user_action message and stop this attempt. |
STATE_CONFLICT | 409 | The operation conflicts with the current state. | This conflicts with the current state. Tell the user; do not retry. |
NO_RAIL | 422 | No rail can serve this purchase; nothing was created. | Envoy cannot pay this purchase. Tell the user why using error.message; do not retry or split it. |
RATE_LIMITED | 429 | Wait before retrying. | Wait next.after_seconds, then retry the same call unchanged. |
UNAVAILABLE | 503 | The service is unavailable; follow retryable and next. | Wait next.after_seconds, then retry the same call unchanged; never pay elsewhere meanwhile. |
CLIENT_UPDATE_REQUIRED | 426 | Update the client. | This client is too old. Tell the user to update it. |