Account and transactions
Read the balance, spendable amount, bank-held money, open purchase money, enabled services and open purchase, and list past transactions, without starting a purchase.
Read this page when a user asks "what is my balance", "can I afford this" or "what did I spend". Both tools are read-only. They never start a purchase and never return card details.
Support revision: envoy@2026-10. Last updated: 28 October 2026.
Who this is for: agent builders and agents answering account questions.
Prerequisites: a connected Envoy account. See the connection guide if the call returns an authentication error.
Success: the reply carries an account or transactions object and no error.
Recovery: if a read fails, call it again. A read changes nothing, so a retry is safe.
Read the account with get_account
Call get_account at the start of a task, or when you lose the purchase reference. With no arguments it returns balance, services, active purchase and the money held in open purchases.
| Field | Meaning |
|---|---|
balance | All money in the account, in INR. |
held | Money the bank holds. This is not a breakdown of agent purchase money. |
held_purchases | Money in open agent purchases: taken from the balance for a one-time card and not yet spent. It comes from the account provider and does not add to held. |
spendable | Money the user can use now. |
services | The services this account and this connection can use. |
active_purchase | The purchase that is open now, or null when none is open. Left out, with active_purchase in unavailable, when Envoy could not read it. |
unavailable | Sections Envoy could not read this time. |
When held_purchases.available is true, items lists open positions. A row can be held, returning or unknown. amount is null when the amount is unknown. When exact is false, treat the amount as “up to” that value. total comes from the account provider. When truncated is true, older rows are missing. When nothing is held, total is zero and items is empty, and the reply's summary doesn't mention it. When the operation is unsupported or unavailable, Envoy marks the section unavailable and does not report zero.
Ask for more with the include argument. Use profile for the verified mobile number. Use addresses for saved delivery addresses. Pass an address ID from that list to start_purchase as address_id.
get_account with include ["balance", "services", "active_purchase"]
get_account with include ["addresses"]A missing value means unknown
Read a missing or unavailable value as unknown. Never read it as unlimited or as zero. Tell the user you could not read it, and do not guess a limit.
What services means
services lists what the account can do here. If purchase is in the list, the purchase service is enabled for this account and connection. If it is missing, stop before you create a purchase and tell the user purchases are not enabled here. A missing service is not a connection failure: the read itself worked.
An enabled purchase service does not prove that KYC is complete or that a live checkout will succeed. KYC happens only in the Envoy app. Funding follows the returned task; a gift-card link is paid by the user themselves.
What active_purchase means
active_purchase points to an open purchase visible to this agent, or is null. It is a recovery pointer, not a complete list of the user's purchases. When it is left out and unavailable lists active_purchase, Envoy could not tell whether a purchase is open. That is not the same as null: don't start a new purchase or pay any other way until a later read shows it. If it keeps happening, tell the user to contact Envoy support with the reference in the reply. Envoy allows up to five open purchases per user, and refuses a second open purchase from the same agent at the same merchant for the same amount. Envoy also refuses a second Envoy-checkout or at-checkout purchase on a site where the user already has an open purchase, at any amount, and allows at most three approvals waiting on the user at once. Read active_purchase before you start another one, and recover it with get_purchase_status instead of starting again.
For a balance or history question, tell the user a purchase is in progress and stop. Resume it only when the user asks. Then use get_purchase_status for that same purchase and follow next; do not start a second purchase to recover it. A ready status call can release credentials. The user can complete the returned approval or payment task, or cancel an eligible purchase in the Envoy app.
List transactions with list_transactions
Call list_transactions for history. It shows the same list as the Envoy app, newest first.
| Argument | Meaning |
|---|---|
limit | Number of transactions, from 1 to 50. |
from, to | Optional dates. from must not be later than to. |
cursor | The next_cursor from the last page. |
The reply carries transactions and next_cursor. When next_cursor is null, you have reached the end.
list_transactions with limit 10
list_transactions with limit 10 and cursor from the last replyPass the cursor back unchanged. It is tied to this connection, the date range and the page size. If you change the range or the limit, start again without a cursor.
Use the skill
The check-envoy-account skill wraps both tools and never moves money. See the skills page to install it.
Next
- Start a purchase: the purchase walkthrough.
- Recover an unclear checkout result: the recovery guide.