API quickstart

The HTTP API exposes every contract tool. The default MCP catalog exposes thirteen; a connection Envoy identifies as Claude receives nine and one identified as ChatGPT receives eight, both omitting report_checkout_result and report_checkout_step. Call the HTTP tools over plain HTTPS: POST https://api.envoy.money/tools/{tool} with a JSON body and a bearer token. No SDK or package is needed. At the end you have read the account.

Support revision: envoy@2026-10. Last updated: 3 November 2026.

This guide makes no purchase. Envoy has no test mode, so the endpoint is production. The purchase guide carries the live-money warning. Every value on this page is synthetic.

Download the OpenAPI document and synthetic examples. The examples hold no real credentials and are not a payment sandbox.

1. Get an access token

Follow OAuth with PKCE: discover the issuer from Envoy's protected-resource metadata, register a public client, have the owner sign in and approve, and exchange the code with scope agent and resource https://api.envoy.money/mcp. Load the access token from private storage at run time; the examples write it as YOUR_ACCESS_TOKEN.

A connection bound to an installation key must also send Envoy-Installation-Proof on every call; see request protection. An ordinary OAuth connection sends only the bearer.

2. Read the account and check services

Call get_account and read data.account.services. A listed tool does not mean purchases are enabled.

POST /tools/get_account HTTP/1.1
Host: api.envoy.money
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{}

The same request with curl, reading the token from an environment variable:

curl -sS https://api.envoy.money/tools/get_account \
  -H "Authorization: Bearer $ENVOY_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{}'

The reply is the shared envelope: HTTP 200 with ok: true, your balance in data.account and next.action continue. It never contains card details. The account comes from the token. No argument can choose another owner.

If data.account.services contains "purchase", the purchase service is enabled. If it does not, the connection can read this account, but purchases are not enabled here. Stop before creating a purchase and follow the service-availability guidance. Do not label a successful account read a connection failure.

If ok is false, the HTTP status matches error.code (for example 401 with UNAUTHENTICATED) and next says what to do. Look the code up in Errors and reason codes.

What success proves

Your Envoy account read succeeded. No purchase was started. If purchase appears in the returned services list, the purchase service is enabled for this account and connection. This check does not prove KYC readiness or that a live checkout will succeed. Before buying anything, review the purchase guide and confirm the merchant and amount with the account owner.

Read Before you start first if you have not set up an Envoy account.

HTTP behavior

• Success and business outcomes return 200. Each error code has its own status, listed in Errors and reason codes. A tool name the server does not serve returns 404 and runs nothing.
• Bodies are JSON objects of at most 64 KB. Invalid JSON returns 400 and an oversized body 413, both with INVALID_INPUT.
• Each access token may make 120 tool calls per minute across /tools and /mcp. Over that, the reply is 429 with RATE_LIMITED and next.after_seconds; wait, then repeat the same call unchanged.
• After a lost reply or a timeout, never pay again: read get_purchase_status first. See Recover a purchase.

All routes, including schema discovery and disconnect, are on HTTP routes. Inputs and outputs for every tool are in the tool reference.

Next steps

• Payment walkthrough: make a purchase with the account owner's approval.
• Recover a purchase: find out what happened after a lost reply or a timeout.
• Tool reference: inputs and outputs for every tool.
• Read the envelope: the shared result shape.