{"templateId":"markdown","sharedDataIds":{},"props":{"metadata":{"markdoc":{"tagList":["admonition","code-group"]},"type":"markdown"},"seo":{"title":"Build with Agents","description":"Official Banxa API documentation – on-ramp and off-ramp transfers with identity verification and compliance.","llmstxt":{"title":"Banxa Developer Documentation","description":"Integrate crypto-fiat exchange with Banxa's licensed infrastructure: payments, KYC, compliance, and settlement handled. 150+ countries, 45 global licences.","details":{"content":"Two integration products: **Banxa Native API** for partners who manage their own KYC and want full UX control (headless, HMAC server-to-server, no Banxa-hosted screens); **Banxa Hosted Checkout** for partners who want Banxa to handle KYC and payments (three paths: Referral URL, API, or React Native SDK). Both use the same sandbox and production environments at `https://api.banxa-sandbox.com` and `https://api.banxa.com`.\n\n## When to use Banxa\n\nReach for Banxa when a product needs to let people **buy crypto with fiat or sell crypto for fiat** without the partner holding money-transmitter or VASP licences. Banxa is the licensed counterparty: it takes the payment, runs compliance, and delivers the asset. Typical fits are wallets, exchanges, dApps, gaming platforms and fintech apps adding an on-ramp or off-ramp.\n\nPick the product by who owns KYC:\n\n- **Banxa Native API** - the partner already runs its own KYC and wants no Banxa screens at all. Headless, HMAC-signed server-to-server, partner owns the entire interface. Needs a backend. Days to weeks to integrate.\n- **Banxa Hosted Checkout** - the partner does not want to run KYC. Banxa handles identity, payment and delivery in its own flow, reached by redirect, embedded iFrame, or React Native SDK. No backend required for the referral path. Hours to days to integrate.\n- **Legacy API** - existing integrations only. Do not start here.\n\nBanxa is not the right tool for crypto-to-crypto swaps, custody or wallet infrastructure, or for any flow where the partner wants to settle funds itself.\n\n## Constraints\n\n- **Authentication**: HMAC credentials must be stored server-side only, never expose in frontend, mobile, or client-side code. HMAC is required for all Native API calls and for KYC sharing in Hosted Checkout; `x-api-key` is used for all other Hosted Checkout endpoints.\n- **`externalCustomerId`**: Required on every buy and sell order. Use a stable opaque identifier, never PII.\n- **`identityReference`**: Must remain constant for the same user across all requests. Must not contain PII. If you attempt to create an identity for an email that already exists, you will receive a 422 / code 81, so retrieve the existing record rather than retrying creation. Use `GET /eapi/v0/identities/{identityReference}?email=user@example.com` to look up the real `identityReference` linked to an email.\n- **`quoteId`**: Only supported by `POST /eapi/v0/ramps` (bank transfer). The React Native SDK and Embedded Payment Button do not accept a `quoteId`, so use indicative pricing (`GET /eapi/v0/price`) for SDK and Embedded Payment Button flows.\n- **Quotes**: Indicative prices are not rate-locked, so refresh close to order creation to minimise rate drift. Locked quotes (`GET /eapi/v0/quote`) expire after approximately 3 minutes and are only valid for bank transfer ramp creation.\n- **Eligibility gate**: Never create a ramp or invoke the SDK when `paymentReady` is `false`. Always check eligibility and satisfy all requirements before payment execution.\n- **Webhooks**: Verify all inbound webhook signatures with HMAC-SHA256 before processing. Return HTTP 200 immediately and process asynchronously.\n- **Product selection**: Banxa Native is for partners who manage their own KYC. Banxa Hosted Checkout is for partners who do not do KYC. These are separate products with separate flows: do not mix endpoints across products.\n- **SDK scope**: The React Native SDK has no `banxa.customerIdentity` module. Identity and KYC are handled through the Native API only. `primerCallbacks` and `primerSettings` are Native context only and must not be referenced in Hosted Checkout integrations.\n- **Payment method naming**: Never use \"eAPI\" or \"EAPI\" as a product name. The correct name is \"Banxa Native API\". The URL path prefix `/eapi/` is correct and should not be changed.\n"}}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"build-with-agents","__idx":0},"children":["Build with Agents"]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For the complete documentation index, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://docs.banxa.com/llms.txt"},"children":["llms.txt"]},". Append ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".md"]}," to any page URL for its markdown version."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This documentation is built to be read by agents as well as by people. Everything"," ","below is read-only, and needs no credentials. It provides the information for your"," ","agent to help you build your integration faster."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Why it matters"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An agent working from a web search may hallucinate and invent endpoints."," ","Pointing it at these documentations means it reads the actual parameter"," ","names, the actual error codes, and the actual auth scheme."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"mcp-server","__idx":1},"children":["MCP server"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These docs run a ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://modelcontextprotocol.io/"},"children":["Model Context Protocol"]}," ","server. An agent connected to it searches and reads the documentation directly"," ","rather than scraping rendered HTML."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"https://docs.banxa.com/mcp\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["It exposes six read-only tools:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Tool"},"children":["Tool"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What it returns"},"children":["What it returns"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["search"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Passages matching a query, across all three products"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["list-apis"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The documented APIs and what each is for"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["get-endpoints"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Every endpoint of one API, with method and path"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["get-endpoint-info"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["One endpoint in full (parameters, schemas, security, examples)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["get-security-schemes"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["How to authenticate against one API"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["get-full-api-description"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The complete OpenAPI description"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The transport is streamable HTTP. Clients must send"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Accept: application/json, text/event-stream"]},"; a request advertising only"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["application/json"]}," is rejected with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["406 Not Acceptable"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"connect-your-client","__idx":2},"children":["Connect your client"]},{"$$mdtype":"Tag","name":"CodeGroup","attributes":{"mode":"tabs"},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","data-title":"Claude Code","header":{"title":"Claude Code","controls":{"copy":{}}},"source":"claude mcp add --transport http banxa-docs https://docs.banxa.com/mcp\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"Cursor","header":{"title":"Cursor","controls":{"copy":{}}},"source":"// .cursor/mcp.json\n{\n  \"mcpServers\": {\n    \"banxa-docs\": {\n      \"url\": \"https://docs.banxa.com/mcp\"\n    }\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"VS Code","header":{"title":"VS Code","controls":{"copy":{}}},"source":"// .vscode/mcp.json\n{\n  \"servers\": {\n    \"banxa-docs\": {\n      \"type\": \"http\",\n      \"url\": \"https://docs.banxa.com/mcp\"\n    }\n  }\n}\n","lang":"json"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once connected, ask the agent questions:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["which Banxa product should I use if I already run my own KYC,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["what does ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /eapi/v0/ramps"]}," accept,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["what does error ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["40003"]}," mean"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A machine-readable description of the server, including the tool list, is available"," ","at ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://docs.banxa.com/.well-known/mcp/server-card.json"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://docs.banxa.com/.well-known/mcp/server-card.json"]}]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"skills","__idx":3},"children":["Skills"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Two skills are published for coding agents. Each is a self-contained instruction"," ","document an agent can fetch and follow, rather than a page it has to interpret."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Skill"},"children":["Skill"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Use it when"},"children":["Use it when"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://docs.banxa.com/.well-known/agent-skills/choose-banxa-integration/SKILL.md"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["choose-banxa-integration"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Deciding between Native API, Hosted Checkout, or other future integration patterns"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://docs.banxa.com/.well-known/agent-skills/banxa-api-authentication/SKILL.md"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["banxa-api-authentication"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Signing requests, and debugging ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]},"s or nonce collisions"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The index is at"," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://docs.banxa.com/.well-known/agent-skills/index.json"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/.well-known/agent-skills/index.json"]}]},","," ","with a SHA-256 digest per skill so a client can verify it fetched the document"," ","the index describes."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"every-page-as-markdown","__idx":4},"children":["Every page as markdown"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Append ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".md"]}," to any documentation URL to get the markdown source instead of"," ","rendered HTML."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl https://docs.banxa.com/products/native-api/docs/getting-started/authentication.md\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"llmstxt","__idx":5},"children":["llms.txt"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Banxa provides ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://llmstxt.org/"},"children":["llms.txt"]}," for LLMs to consume our documentation on their own."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A condensed version of the documentation is available at ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://docs.banxa.com/llms.txt"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/llms.txt"]}]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The full corpus is available at ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://docs.banxa.com/llms-full.txt"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/llms-full.txt"]}]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"api-catalog","__idx":6},"children":["API catalog"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://docs.banxa.com/.well-known/api-catalog"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://docs.banxa.com/.well-known/ai-catalog.json)"]}]}," is an"," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://www.rfc-editor.org/rfc/rfc9727"},"children":["RFC 9727"]}," catalog listing every Banxa"," ","API with its reference documentation and status endpoint, so a client can"," ","enumerate what exists before fetching anything."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"in-browser-tools","__idx":7},"children":["In-browser tools"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"WebMCP is an emerging standard"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["While it is  still stabilising in Chrome, please treat this feature as experimental"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Pages on this site register ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://webmachinelearning.github.io/webmcp/"},"children":["WebMCP"]}," ","tools, so a browser-resident agent can search these docs and look up endpoints"," ","without leaving the page."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"crawling-policy","__idx":8},"children":["Crawling policy"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://docs.banxa.com/robots.txt"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/robots.txt"]}]}," names the AI crawlers explicitly and declares how Banxa prefers this"," ","documentation to be used. Answer-engine crawlers are welcome. A"," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://docs.banxa.com/sitemap.xml"},"children":["sitemap"]}," lists every canonical page."]}]},"headings":[{"value":"Build with Agents","id":"build-with-agents","depth":1},{"value":"MCP server","id":"mcp-server","depth":2},{"value":"Connect your client","id":"connect-your-client","depth":3},{"value":"Skills","id":"skills","depth":2},{"value":"Every page as markdown","id":"every-page-as-markdown","depth":2},{"value":"llms.txt","id":"llmstxt","depth":2},{"value":"API catalog","id":"api-catalog","depth":2},{"value":"In-browser tools","id":"in-browser-tools","depth":2},{"value":"Crawling policy","id":"crawling-policy","depth":2}],"frontmatter":{"title":"Build with Agents | Banxa Docs","description":"Connect AI coding agents to the Banxa documentation over MCP, load it as markdown, and read the published skills — so your agent works from the source instead of guessing.","seo":{"title":"Build with Agents"}},"lastModified":"2026-08-20T06:59:29.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/ai/build-with-agents","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}