An OpenAPI spec for a stablecoin or payments API is a machine-readable file listing endpoints, fields and allowed values, so developers can import it and coding agents can read exact names instead of guessing. A docs MCP server lets an agent search and read the documentation inside its own session. Together they cover what you read before a first call.
This post covers that reading surface for a payments API: what a complete spec contains, what an agent can and cannot do through a docs server, and where each piece lives on Lumx. The definition of the API itself is in what a stablecoin API is, and the order of the integration steps is in the integration guide.
What an OpenAPI spec does for a payments integration
OpenAPI is a standard format for describing an HTTP API. One file lists the paths, the methods, the fields each request takes, the values each field allows, the authentication scheme and the shape of each response.
Three jobs follow from that. Import tools such as Postman or Insomnia turn the file into a ready collection of requests. Generators turn it into a typed client in your language, so a renamed field breaks the build instead of production. And an agent reads it to learn the real names and enums before it writes a line.
The third job has grown the most. A coding agent writing a payments call from memory invents plausible field names, and a plausible wrong value is expensive: a rejected request at best, and at worst a payment on the wrong rail that costs a reversal or a round of questions from the bank. Correspondent banking taught the industry to live with a PDF wire guide and a phone call. An enum an agent can grep is a better deal. Reading the spec first removes the guess.
On Lumx, the contract is a file in OpenAPI 3.1 format named Lumx API. It describes 31 operations in seven resource groups: customers, accounts, destinations, exchange rates, transactions, partner fees and autoconversion rules. Authentication is a bearer API key, and the server listed in the file is the sandbox.
Where the spec lives and what each docs page adds
The OpenAPI page of the docs, at docs.lumx.io/developer/openapi, links the production file (also served at docs.lumx.io/openapi/api-production.yaml) and lists the import steps for Postman, Insomnia, OpenAPI Generator and Swagger Editor. Every endpoint page embeds the slice of that same file, and the docs MCP can read the file from inside a session. Read the production file, not a staging one: the docs prompts name a staging spec beside it, and the production file is the one the OpenAPI page links.
The same content is reachable in smaller pieces. Every endpoint has its own page on the docs host. Any docs page can be fetched as markdown, either by adding .md to its address or by sending an Accept header for text/markdown, and the docs host publishes an llms.txt index listing the pages. An agent that cannot load a file of about 330 KB can still read one operation at a time.
On Lumx, the pages an integration needs beyond the spec are Authentication, Environments, Webhooks, Idempotency and Errors under the same docs host, and the coverage page lists rails and supported pairs. Rails and currencies come from coverage, not from the spec.
How much of a payments API spec is described, and how do you measure it?
Description coverage is measurable: how many operations carry a description, how many fields carry one, and whether the examples are named. An undescribed field forces the reader, human or agent, to guess, and the spec exists to remove the guess. This is one measure, not a verdict on the whole spec.
We counted both specs on November 1, 2026, with the same script. A property is any field inside any schema object, nested ones included, and it counts as described when its description is not empty.
Description coverage only, not completeness, of the published OpenAPI files, counted on November 1, 2026.
Measure | Lumx | BlindPay |
OpenAPI version | 3.1.0 | 3.1.0 |
Operations | 31 | 105 |
Operations with a description | 31 (100%) | 28 (27%) |
Fields with a description | 869 of 945 (92%) | 1,179 of 3,062 (39%) |
A description can exist and say nothing, so the count is a floor on quality, not a ceiling. It also does not show other things a buyer should count: documented error responses, webhook definitions and operationIds. Count those too before you compare two specs.
Named examples are the other half. A field list tells an agent which values are allowed, and an example tells it which combination actually works together. The on-ramp operation in the Lumx file carries 14 named request examples, a floating-rate and a locked-rate version for each of seven rails: Pix (Brazil's instant payment system, run by the Central Bank), SPEI (Mexico's interbank transfer system, run by Banxico), ACH, SEPA, SWIFT, FEDWIRE (the Federal Reserve's same-day wire system) and Faster Payments (the UK's real-time bank transfer network). Pick the example named for your rail and change the amounts.
A check you can hand to engineering has three questions. Does the spec list each rail you need? Are the examples named by case? What does the agent still have to read elsewhere? The third answer is the one to forward.
On Lumx, the endpoint pages embed the production file, the same file the OpenAPI page names, and the file header declares 3.1.0. Errors and webhooks have their own pages, Errors and Webhooks, so read those beside the spec.
What a docs MCP server adds for a coding agent
MCP is the Model Context Protocol, the open standard coding assistants use to connect to outside tools. A docs MCP server is one that exposes documentation: the agent asks it a question or opens a file, and the answer comes from the published docs, not from the model's memory.
A good docs server has few tools: one searches, one reads, so the agent can open a spec, find an enum with a pattern match and quote it. Neither needs a secret, because the content is already public. That is also the boundary: a server that only reads documentation cannot create a customer, quote a rate or move money, and an agent that believes otherwise has been told something wrong. Money moves through the REST API with a server-side key, which the docs server never sees.
On Lumx, the server is at docs.lumx.io/mcp with no authentication and two tools: search_lumx for semantic search across the docs and query_docs_filesystem_lumx for shell-style reads of the raw pages and the spec. The setup is one line per host for Claude Code, Cursor, VS Code, Codex and Claude Web, listed on the MCP server page. The docs MCP connection prompt installs it, verifies the tool list and makes the agent prove the connection by comparing field names from memory against the spec.
Make the agent read before it writes
The cheapest control on an agent-built integration is a rule about order: no field name, enum value or path goes into code until it has been read from the spec in the same session. The rule costs one search per field.
I recommend making that rule the first line of any prompt that touches a payments API, and checking it with a diff before anything else runs: ask the agent to write the request body from memory, then from the spec, and compare the two lists. If they match, the agent was reading anyway. If they differ, you have just seen the failure in a sandbox, where it cost nothing.
On Lumx, the sandbox is a separate base URL at api-sandbox.lumx.io with test stablecoins and mock banking partners, so the diff runs without real money. The prompt library has one prompt per task, and each begins by naming the pages and the spec the agent must read first.
Which surface answers which question?
A docs surface has a place for each need.
The reading surfaces of a payments API, what each is for, and what each cannot do.
Surface | Answers | Cannot do | On Lumx |
OpenAPI file | Exact paths, fields, enums, auth, request examples | Say which call comes first, or what an event means | 31 operations, bearer key, sandbox server, production file linked from docs.lumx.io/developer/openapi |
Docs MCP server | Lets an agent search and read the docs and the spec in its own session | Move money, hold a key, replace the REST API | docs.lumx.io/mcp, no key, two tools |
Markdown pages and llms.txt | One page at a time, in a form models read cheaply | Show the whole contract in one request | Every docs page as markdown, with an index at docs.lumx.io/llms.txt |
Prompt library | Literal steps and constraints for one task | Replace reading the spec | Copy-paste prompts per task, listed at docs.lumx.io/prompts/overview |
REST API | The actual calls | Be tested safely without a sandbox | api-sandbox.lumx.io to build, api.lumx.io for production |
For a buyer, the same table is a checklist, and choosing an infrastructure provider shows where documentation sits among the other criteria. Agents also read the compliance side of these APIs, covered in compliance agents for cross-border payments.
On Lumx, the sandbox is open and self-serve, so it is where every one of these surfaces gets used first.
When the spec and the docs MCP are the wrong tool
The spec is the wrong place to learn how a payment behaves. It lists the request, not the lifecycle: the statuses a transaction passes through, the compliance hold that asks for a document before money moves, the cut-off time of a rail. An agent that builds only from field lists will compile and still misunderstand the flow. For the order of calls, read the integration guide.
The docs server is the wrong tool for anything that must act. It reads. If your agent needs to create a customer or start a payout, the call goes through the REST API with a key held on your server, and a human should approve any step that moves money. Do not hand an agent a production key to save a step. On Lumx, the Authentication page lists an IP allowlist for production keys, with the docs giving September 21, 2026 as the date enforcement starts, and the key stays on your server; those two controls sit around any agent-built integration.
Generating a client is the wrong move when you make three calls. For a small integration, a hand-written request with the spec open beside it is shorter than a generator in the build.
On Lumx, the sequence of customer, verification, account or wallet, and transaction is described on the concept and guide pages, and the status of each object arrives as webhook events listed on the Webhooks page. Adding stablecoin payments to an app walks that sequence call by call.
What this looks like on a Lumx integration
Lumx is stablecoin payments infrastructure for businesses that move money between Latin America and the rest of the world: one API to collect, hold, convert, and pay out in BRL, MXN, COP, USD, EUR, and GBP or in USDC and USDT, over local rails such as PIX, SPEI, PSE, Bre-B, ACH, FEDWIRE, SEPA, and Faster Payments, with SWIFT and on-behalf-of payments and collections (POBO and COBO) in USD, EUR, and GBP, plus named virtual accounts, custodial wallets, and KYB/KYC built in.
Integration on Lumx is a REST API, the OpenAPI file and the docs MCP server. There is nothing to install: the calls are plain HTTPS with a bearer key, and a typed client in your language comes from running the file through a generator. Start by connecting the docs server to your agent, then ask it to read the production spec and list the fields of the on-ramp request for your rail before it writes the route.
Around the request, three behaviors are documented on their own pages. Every write accepts an Idempotency-Key header with a UUID, a repeated key with the same body returns the cached response, and the same key with a different body returns a conflict. Every error uses one response shape with a machine-readable code, so handle failures by code and not by message. Every status change arrives as a signed webhook with an event ID and an event type, which is where a payout moves from pending to done in your system.
What changed in the API and the docs is in the API changelog, the rails and currencies each corridor supports are on the coverage page, and the product view of the same surface is global payments. Running several providers behind one flow is covered in payment orchestration with stablecoins.
Methodology and sources
Product facts were read on November 1, 2026 from the Lumx docs: OpenAPI Specification, MCP Server, Connect your agent to the Lumx docs MCP, Ship with AI, Prompts for coding agents, Webhooks, Idempotency, Errors, Authentication and Environments, plus the server's tool list in its published server card.
The Lumx numbers come from the production OpenAPI file linked on the OpenAPI page, whose header declares openapi 3.1.0. The BlindPay numbers come from the OpenAPI document BlindPay publishes for its API, fetched the same day. Both were parsed with one script. Operations counted are those with a method under a path. Fields counted are every key under a properties object, at any depth, and a field is described when its description is non-empty. The format is defined by the OpenAPI Specification 3.1.0.
Verified on November 1, 2026. Operational context, not legal, tax, or investment advice.
Cover photo: Chris Bair on Unsplash.
Where is the Lumx stablecoin API OpenAPI spec?
The OpenAPI page of the Lumx docs, at docs.lumx.io/developer/openapi, links the production file and shows how to import it into Postman, Insomnia, Swagger Editor or OpenAPI Generator. It is an OpenAPI 3.1 file with 31 operations. Every endpoint page embeds the slice of the same file, the docs MCP can read it inside a session, and any docs page can be fetched as markdown.
Can I generate a client from the OpenAPI spec of a stablecoin API?
Yes, any OpenAPI 3.1 file can go through a generator for the language you use, and a generated client follows the spec by construction. On Lumx, the OpenAPI page names OpenAPI Generator as the way to produce a client, and integration is otherwise the REST API with a bearer key and the docs MCP server for lookups.
What is a docs MCP server, and can an AI agent move money through it?
A docs MCP server lets a coding agent search and read documentation through the Model Context Protocol. It cannot move money, because it reads published pages and has no access to the API or a key. On Lumx, the server is at docs.lumx.io/mcp with no authentication and two tools, search_lumx and query_docs_filesystem_lumx, and payments go through the REST API with a server-side key.
How do I connect Claude Code or Cursor to the Lumx docs?
Add the server URL docs.lumx.io/mcp to your host. For Claude Code the line is claude mcp add --transport http lumx-docs https://docs.lumx.io/mcp, and Cursor, VS Code, Codex and Claude Web each take a short config block from the MCP server page. The Lumx prompt library has a copy-paste prompt that installs it and checks the tool list.
How do I know a payments API spec is good enough for an agent?
Count the operations and fields that carry a description, check whether the examples are named by case, count documented error responses, webhook definitions and operationIds, and test it: ask an agent for a request body from memory, then from the spec, and compare. On Lumx, all 31 operations have a description and 92 percent of fields do, as of November 1, 2026, which is description coverage only. The on-ramp operation has named examples for each of seven rails, and errors and webhooks have their own pages.
