> ## Documentation Index
> Fetch the complete documentation index at: https://public-openfx.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Coding agents

> Give your coding agent the OpenFX v3 rules, docs, and task prompts so it builds a correct integration in any language.

Use an AI coding agent to build an OpenFX v3 integration in the language and framework you already use. You give the agent three things: the OpenFX documentation, a short rules file that prevents the most common integration mistakes, and a prompt for the task.

## Choose your starting point

| You want to | Start with |
| - | - |
| Ask an AI app about your own trades, deposits, and withdrawals | [MCP connectors](https://public-openfx.mintlify.site/v3/mcp-connectors.md) |
| Build an integration with a coding agent | [Add the rules file and skill](#add-the-rules-file-and-skill) and the [prompt library](#prompt-library) |
| Ask a chat assistant a quick question about the API | [Machine-readable docs](#machine-readable-docs) |

> [!NOTE]
>
> The OpenFX MCP connector reads your account data and is read-only. It does not read this documentation and can't place trades or move funds. Your coding agent writes code that calls the API with your Sandbox API key.

## Before you begin

* **A Sandbox API key file.** The key JSON contains `kid` and `privateKey`, and Sandbox keys carry a `sandbox_` prefix. See [Authentication](https://public-openfx.mintlify.site/v3/authentication.md) and [Environments](https://public-openfx.mintlify.site/v3/environments.md).
* **A coding agent** that reads an `AGENTS.md` file or a project instruction file, such as Claude Code, Codex, Cursor, or GitHub Copilot.

> [!WARNING]
>
> Build and test against Sandbox first. Sandbox and Live use the same endpoints and code, so going live means changing the API key, the webhook signing secret, and the `X-App-Mode` value in configuration. Never paste an API key, private key, or webhook signing secret into a chat. Give the agent the path to the key file or the name of an environment variable.

## Machine-readable docs

Point your agent at these files so it reads the documentation instead of guessing.

| File | What it contains | Use it for |
| - | - | - |
| `https://docs.openfx.com/llms.txt` | An index of every documentation page | Coding agents. The agent reads the index first, then the pages for your task. |
| `https://docs.openfx.com/llms-full.txt` | The full documentation in one file | Chat assistants that can't open links. The file is large, so avoid it in coding agents. |

Where a guide page and the OpenAPI specification disagree, the specification is the contract.

## Add the rules file and skill

Add `AGENTS.md` to your repository so every coding agent starts with the OpenFX v3 rules. Add the skill if you use Claude Code. Commit both so every contributor and agent session uses the same rules. They link to the documentation instead of copying it, so they stay current when the documentation changes.

> [accordion] AGENTS.md
>
> `AGENTS.md` is a plain Markdown file at the root of your repository that coding agents read before they work. Copy this file into your repository. It states each rule briefly and links to the page that owns the detail.
>
> ```text AGENTS.md theme={"theme":{"light":"poimandres","dark":"poimandres"}}
> # OpenFX v3 integration rules
>
> This repository calls the OpenFX v3 API. Follow these rules in every change that touches OpenFX.
>
> ## Sources of truth
>
> - Read https://docs.openfx.com/llms.txt first, then the pages for the task.
> - The OpenAPI specifications define the wire contract. If a guide page and the specification disagree, follow the specification and report the disagreement.
> - Cite the docs page for every endpoint you use. Do not guess an endpoint, field, error code, or event name. If the docs do not cover it, say so.
>
> ## Environment and secrets
>
> - Build and test against Sandbox first. Sandbox and Live use the same endpoints and code, so keep the API key, webhook signing secret, and `X-App-Mode` value in configuration. Switch to Live by changing those values, and only when a human asks you to.
> - Read the API key from a file path or an environment variable. Never ask for, print, log, or commit a private key, JWT, or webhook signing secret.
> - Send `X-App-Mode` on every request, set to the environment of the key in use (`SANDBOX` or `LIVE`). Never rely on the header being optional.
> - Keep Sandbox and Live keys and webhook secrets in separate configuration entries. Sandbox ids are not Live ids.
> - See https://docs.openfx.com/v3/environments.
>
> ## Authentication
>
> - Every request carries a fresh ES256 JWT bearer token (60 seconds maximum lifetime, a unique `nonce` in the header) and an `X-Request-Signature` header.
> - The request signature uses IEEE P-1363 encoding, not DER, and covers the exact body bytes you send. Serialize the body once.
> - Build the signing helper from https://docs.openfx.com/v3/authentication. Do not reuse a JWT or a nonce.
>
> ## Requests and responses
>
> - Routes: FX under `/v3/fx/...`, Payments under `/v3/payments/...` and `/v3/common/...`. The base URL is `https://api.openfx.com`.
> - Amounts are JSON strings. Parse them as decimals, never floats. See https://docs.openfx.com/v3/amounts.
> - Responses wrap the result in a `data` object. Most list endpoints use cursor pagination with `limit`, `startingAfter`, and `endingBefore`, and return a `pagination` object. `GET /v3/fx/pairs`, `GET /v3/fx/balances`, and `GET /v3/common/financial-accounts` return the complete `data` array with no cursor parameters or `pagination`. See https://docs.openfx.com/v3/pagination.
> - Send an `Idempotency-Key` on every write. Create one key per logical operation, store it before you send the request, and reuse the same key to retry. See https://docs.openfx.com/v3/idempotency.
>
> ## Errors and rate limits
>
> - Branch on `error.code` and the retry strategy in the error response, not on the HTTP status alone. See https://docs.openfx.com/v3/errors.
> - Cap retries and back off. On `429`, wait for `Retry-After`. See https://docs.openfx.com/v3/rate-limiting.
>
> ## Webhooks
>
> - Verify the signature on the raw request body before you parse it, compare in constant time, and deduplicate by event `id`.
> - Handlers must tolerate duplicate and out-of-order events. Refetch the resource by id when in doubt.
> - See https://docs.openfx.com/v3/webhooks/setup and https://docs.openfx.com/v3/webhooks/authentication.
>
> ## Working agreement
>
> - Ask which language and HTTP client the repository uses if it is not obvious.
> - Keep a reusable signing helper, a thin API client, and tests that run against Sandbox. Do not hard-code credentials or resource ids.
> - Report which pages you read and anything you could not verify.
> ```
>
> Claude Code reads `CLAUDE.md`, not `AGENTS.md`. If your repository doesn't already have a `CLAUDE.md`, create one that contains the single line `@AGENTS.md` so Claude Code loads the same rules.

> [accordion] SKILL.md (Claude Code)
>
> A skill packages a repeatable workflow that Claude Code loads when a request matches its description. Save this file as `.claude/skills/openfx-integration/SKILL.md` in your repository. It sends the agent to the rules file and the matching task prompt, so the rules stay in one place.
>
> ```text SKILL.md theme={"theme":{"light":"poimandres","dark":"poimandres"}}
> ---
> name: openfx-integration
> description: Build, debug, or review an OpenFX v3 API integration. Use when the task involves OpenFX FX quotes and trades, payouts, deposits, withdrawals, request signing, or webhooks.
> ---
>
> # OpenFX v3 integration
>
> 1. Read `AGENTS.md` in the repository root and follow it. If it does not exist, stop and ask the user to add it from https://docs.openfx.com/v3/coding-agents.
> 2. Read https://docs.openfx.com/llms.txt, then read the docs pages for the task.
> 3. Find the matching prompt in the prompt library at https://docs.openfx.com/v3/coding-agents and follow its steps.
> 4. Work against Sandbox first, and keep the key and `X-App-Mode` in configuration so going live is a configuration change. State which pages you read and what you could not verify.
> ```
>
> Codex, Cursor, and GitHub Copilot read `AGENTS.md` or their own instruction files directly. Skills are specific to Claude Code.

## Prompt library

Each prompt tells the agent which pages to read, what to build, and what to deliver. The prompts point to the documentation for contract details, so they stay correct when the documentation changes.

### Use a prompt

**1. Copy a prompt**

Choose the prompt for your task below and copy its code block.

**2. Paste it into your agent**

The agent asks for your language, HTTP client, and the path to your Sandbox key file. Answer with paths and names, not secrets.

**3. Review and keep the output**

Read the code the agent writes, run its tests against Sandbox, and commit the helpers and tests so you can rerun them.

Each prompt assumes the agent can read `https://docs.openfx.com`. If it can't fetch URLs, paste the pages it names into the conversation.

### Start here

> [accordion] Ask a question about the API
>
> Use this in a chat assistant when you don't have a coding agent open yet.
>
> ```text theme={"theme":{"light":"poimandres","dark":"poimandres"}}
> Read the OpenFX API docs at https://docs.openfx.com/llms.txt and help me integrate with the OpenFX v3 API. Start by asking what I want to build (FX trades, payouts, deposits, withdrawals, or webhooks) and which language I use. Start with Sandbox (X-App-Mode: SANDBOX) and keep the key and X-App-Mode in configuration so going live is a configuration change. Never ask me to paste a Live key or private key, and cite the docs page for every endpoint you use.
> ```

> [accordion] Sandbox quickstart
>
> Builds a signing helper, a thin client, and a smoke script that completes one Sandbox trade.
>
> ```text theme={"theme":{"light":"poimandres","dark":"poimandres"}}
> Set up a working OpenFX v3 Sandbox integration in this repository and prove it with one completed FX trade.
>
> Read first: https://docs.openfx.com/llms.txt, https://docs.openfx.com/v3/quickstart, https://docs.openfx.com/v3/authentication, https://docs.openfx.com/v3/environments, https://docs.openfx.com/v3/amounts, and https://docs.openfx.com/v3/idempotency. Where a guide page and the OpenAPI specification disagree, follow the specification and tell me about the disagreement.
>
> Before you write code, ask me for my language, my HTTP client, and the path to my Sandbox API key file. Never ask me to paste the key.
>
> Build, in order:
> 1. A signRequest helper that follows the Authentication page exactly and mints a fresh JWT and signature for every request.
> 2. A thin client for https://api.openfx.com that reads the API key and X-App-Mode from configuration (SANDBOX for now) and unwraps the data envelope.
> 3. A smoke script that lists pairs, lists balances, creates a quote, executes a trade from the quote, and fetches the trade by id. Use a different Idempotency-Key for each write.
> 4. Output that prints every created resource id and the final trade status.
>
> On any failed call, print error.code, error.message, and the retry strategy, not only the HTTP status.
>
> Deliver the helper, the client, the smoke script, an example environment file, and a short README that explains how to run it and how to switch to Live later.
> ```

### Build a flow

> [accordion] FX quotes and trades
>
> Builds the conversion flow: discover pairs, quote, execute before expiry, and track the trade.
>
> ```text theme={"theme":{"light":"poimandres","dark":"poimandres"}}
> Build an FX conversion feature on the OpenFX v3 API in this codebase: discover pairs, create a quote, show the price, execute the trade, and track it.
>
> Read first: https://docs.openfx.com/v3/trades, https://docs.openfx.com/v3/quotes, https://docs.openfx.com/v3/currencies, https://docs.openfx.com/v3/amounts, https://docs.openfx.com/v3/idempotency, https://docs.openfx.com/v3/pagination, https://docs.openfx.com/v3/errors, and the Trade pages of the API reference. Assume a working signing helper exists. If not, build it first from https://docs.openfx.com/v3/authentication.
>
> Requirements:
> - Validate user input against the pairs endpoint.
> - Show the amounts the quote returns. Don't invent fields the API doesn't return.
> - Use a separate Idempotency-Key for the quote and for the trade, one per logical operation.
> - Handle quote expiry by re-quoting and asking the user to confirm. Never execute silently at a new price.
> - Store each Idempotency-Key before you send the request. Replay with the same key after a timeout. If the trade returns TRADE_EXECUTION_FAILED, look it up by ID. If it exists, track it. If the lookup confirms it is missing, get a fresh quote and submit the trade with a new key.
> - Represent amounts with a decimal type end to end.
>
> Deliver a service module, Sandbox tests for the happy path, quote expiry, and a duplicate submit, and a short list of every error code the module handles.
> ```

> [accordion] Trade settlement and reversals
>
> Builds settle and reverse flows for the settlement model your organization uses.
>
> ```text theme={"theme":{"light":"poimandres","dark":"poimandres"}}
> Add post-trade settlement and reversal handling to this OpenFX v3 integration.
>
> Read first: https://docs.openfx.com/v3/settlement-models, https://docs.openfx.com/v3/trades (the state machine, settle, and reverse sections), https://docs.openfx.com/v3/exposure, https://docs.openfx.com/v3/balances, https://docs.openfx.com/v3/idempotency, https://docs.openfx.com/v3/webhooks/setup, the Trade event pages under Webhooks, and the settle, reverse-quote, and reverse operations in the API reference.
>
> Ask me which settlement model my organization uses before you write code, and implement only what that model needs. The field tradeSettlementMode appears only in trade webhook payloads. It isn't on the REST Trade resource, so don't look for it there.
>
> Build:
> 1. The trade state machine from the Trades page, driven by trade webhook events, with the trade endpoint as the fallback.
> 2. Settlement for per-trade organizations: settle a trade when it is ready to settle, with its own Idempotency-Key, and confirm the result from the trade webhook or by fetching the trade.
> 3. Reversal: create a reverse quote, show the reversal price to the user, then reverse the trade. Use a separate Idempotency-Key for each call and handle quote expiry.
> 4. Exposure and balances: show exposure that settles later so operations don't treat it as stuck, and read withdrawableBalance separately from totalBalance after settlement.
>
> Trade webhooks are delivered only to Live webhook endpoints. In Sandbox, poll the trade endpoint, and keep the polling path in production as a fallback. Handlers must be idempotent and tolerate duplicate and out-of-order events.
>
> Deliver the settlement and reversal services, the webhook handlers, tests for settle, a duplicate event, an out-of-order event, and reversal quote expiry, and a state diagram of the trade states you handle.
> ```

> [accordion] Payouts end to end
>
> Builds recipients, payout addresses, quotes, payouts, confirmation, and lifecycle tracking.
>
> ```text theme={"theme":{"light":"poimandres","dark":"poimandres"}}
> Build a payout feature on the OpenFX v3 Payments API: create recipients, register payout addresses, price a payout, send it, and track it to a terminal state.
>
> Read first: https://docs.openfx.com/v3/payouts, https://docs.openfx.com/v3/account-model, https://docs.openfx.com/v3/capabilities, https://docs.openfx.com/v3/supported-networks, the payout integration guide for each currency I ask about, the Payments pages of the API reference, and the payout, account, and payout-address pages under Webhooks. The Payments OpenAPI specification is the source of truth where pages disagree.
>
> Ask me which currencies and corridors I need before you write code.
>
> Requirements:
> - Follow the order of operations and the required capabilities on the Payouts and Capabilities pages.
> - Build a state machine for the payout status values the specification defines, driven by payout webhooks, with the payout endpoint as the fallback. Handle a payout that is created already failed.
> - Send an Idempotency-Key on every write. Carry your own ids in metadata.
> - Show the fee breakdown from the payout quote.
> - Handle capability and address verification states asynchronously.
> - If a Payments call returns 403 AUTH_INSUFFICIENT_SCOPE, tell me my API key lacks Payments access, record the exact response, and continue with the tests that don't call the API.
>
> Deliver services for accounts, payout addresses, and payouts, the webhook handler, a status-machine test suite (happy path, rejected address, quote expiry, failed payout), and a sequence diagram.
> ```

> [accordion] Webhooks end to end
>
> Builds one receiver for every event family with signature verification, deduplication, and state tracking.
>
> ```text theme={"theme":{"light":"poimandres","dark":"poimandres"}}
> Build a production webhook receiver for every OpenFX v3 event we subscribe to.
>
> Read first: https://docs.openfx.com/v3/webhooks/setup, https://docs.openfx.com/v3/webhooks/authentication, every event page under Webhooks, and the webhook definitions in both OpenAPI specifications. Where a page and the specification differ on the signature header or scheme, follow the specification and tell me.
>
> Build:
> 1. One endpoint that captures the raw body bytes before parsing and verifies the signature in constant time, with the replay window the documentation specifies.
> 2. Separate signing secrets per environment, loaded from configuration.
> 3. Storage for each event (id, type, payload, received time). Return 2xx immediately and process from a queue.
> 4. Deduplication on event id, and handlers that are idempotent and tolerate out-of-order delivery by comparing against the resource's current state.
> 5. State updates for deposits, withdrawals, trades, accounts, payout addresses, and payouts.
> 6. A fallback poller for each resource type, because any webhook can be missed.
>
> Deliver the receiver, verifier unit tests (valid, tampered, wrong secret, stale timestamp), the handlers, and a table that maps each event to the state change it causes.
> ```

> [accordion] Idempotency and retries
>
> Builds persisted idempotency keys, crash recovery, and error-driven retries for every write.
>
> ```text theme={"theme":{"light":"poimandres","dark":"poimandres"}}
> Add a shared idempotency and retry layer in front of every OpenFX v3 write call in this codebase.
>
> Read first: https://docs.openfx.com/v3/idempotency (including crash recovery and TTL alignment), https://docs.openfx.com/v3/errors (the retry strategy values and the triage guidance), and https://docs.openfx.com/v3/rate-limiting. Take each endpoint's key lifetime from the Idempotency page and the API reference page for that operation. If an endpoint documents no lifetime, use a conservative default, make it configurable, and tell me which endpoints use it.
>
> Build:
> 1. A persistence table for writes (key, endpoint, request body, status, resource id, response body, HTTP status, created and completed times). Insert the row before you send the request.
> 2. One Idempotency-Key per logical operation. A quote and the trade that uses it are two operations with two keys. Include Payments writes.
> 3. Routing by the retry strategy in the error response, exactly as the Errors page defines each value. Retry with the same key when the strategy says so, check the resource's state before retrying when it says so, and use a new key when resubmitting a corrected request or starting a new operation. For FX trade execution or withdrawal initiation failures, confirm that the resource is missing before starting a new operation. Stop on terminal errors.
> 4. Handling for a request that is still in flight and for a key reused with a different body. Treat a key reused with a different body as a bug and alert on it.
> 5. A recovery worker that replays rows stuck in flight with the same key, signs each replay with a fresh JWT and request signature, and stops before the endpoint's key lifetime expires.
> 6. Capped retries with backoff. On 429, wait for Retry-After.
>
> For FX writes that time out, reuse the existing key within the idempotency window. After a trade execution or withdrawal initiation failure, complete the resource lookup before submitting a new write.
>
> Deliver the table migration, the wrapper, the recovery worker, and tests for a crash after send, a request in flight, a mismatched body, and a 429.
> ```

### Debug and review

> [accordion] Implement or debug request signing
>
> Builds a tested JWT and `X-Request-Signature` helper, or diagnoses `401` and `403` responses from an existing one.
>
> ```text theme={"theme":{"light":"poimandres","dark":"poimandres"}}
> Implement or fix OpenFX v3 request authentication in this codebase, and prove it works against Sandbox.
>
> Read first: https://docs.openfx.com/v3/authentication completely, including the path canonicalization steps and the language samples, https://docs.openfx.com/v3/errors for the authentication and authorization codes, and https://docs.openfx.com/v3/environments. Ask me which language and HTTP client we use if the repository doesn't make it clear.
>
> Step 1, find out where we are. If the repository has no signing helper, build signRequest({ method, url, body }) so it returns the headers and the exact body bytes to send, following the page for the JWT claims and header, the canonical string, path and query canonicalization, and the P-1363 signature encoding. If a helper exists and requests fail, start from the exact error response for a failing request: error.code, message, details, and the request id. Map the code to its cause using the Errors page. Never print the private key or the full token.
>
> Step 2, for signature failures, check in this order:
> 1. The path you signed against the path you sent, after canonicalization. Watch for double slashes and base URL joins.
> 2. The body bytes you hashed against the bytes you sent. Watch for re-serialization and pretty-printing.
> 3. DER against P-1363 signature encoding.
> 4. Query string sorting and encoding.
> 5. The nonce in the signature against the nonce in the JWT header.
> Also check the JWT claims and lifetime, and never reuse a JWT or a nonce.
>
> Step 3, check the environment: key prefix, X-App-Mode, and, for Live keys, the IP allowlist.
>
> Step 4, add temporary debug logging that prints the canonical string and the decoded JWT header and claims. Reproduce the failure, fix it, and remove the logging.
>
> Step 5, add unit tests that prove:
> - A path with a doubled slash and a path with a dot segment canonicalize to the same path as the clean path.
> - Query parameters are sorted by key, then value.
> - The raw signature is exactly 64 bytes before base64url encoding.
> - Re-serializing the body changes the hash, and the helper returns the exact bytes it hashed.
> - Every call gets a new nonce and a JWT lifetime of at most 60 seconds.
>
> Step 6, make one Sandbox call to list pairs using the key file path I give you, and show me the response status. If I haven't given you a key file path, say so and skip this step.
>
> Report the root cause if there was one, the fix, and the tests you added.
> ```

> [accordion] Review an existing integration
>
> Audits an integration against the v3 contract and ranks findings by risk to money.
>
> ```text theme={"theme":{"light":"poimandres","dark":"poimandres"}}
> Audit this codebase's OpenFX v3 integration for correctness and resilience. Don't change code. Produce a ranked findings report.
>
> Read first: https://docs.openfx.com/llms.txt, then https://docs.openfx.com/v3/authentication, https://docs.openfx.com/v3/environments, https://docs.openfx.com/v3/amounts, https://docs.openfx.com/v3/idempotency, https://docs.openfx.com/v3/errors, https://docs.openfx.com/v3/rate-limiting, https://docs.openfx.com/v3/pagination, https://docs.openfx.com/v3/webhooks/authentication, https://docs.openfx.com/v3/live-checklist, and the OpenAPI specifications. Where a guide page and the specification disagree, follow the specification and tell me.
>
> Check each area and cite the file and line:
> 1. Authentication: a fresh JWT and nonce per request, a lifetime of at most 60 seconds, a request signature with P-1363 encoding, and body bytes hashed equal to the bytes sent.
> 2. Environment: X-App-Mode sent explicitly and derived from the same configuration as the key, and Sandbox and Live secrets stored separately.
> 3. Money: amounts are strings and parsed as decimals everywhere, with no floats.
> 4. Idempotency: a key on every write, including settle, reverse, and Payments writes, stored before sending, reused on retry, and unique per logical operation.
> 5. Errors: handling branches on error.code and the retry strategy, retries are capped, and unknown codes reach a generic handler.
> 6. Rate limits: 429 handling that honors the documented headers.
> 7. Webhooks: verification on the raw body, constant-time comparison, the replay window, deduplication by event id, asynchronous processing, and a fallback poller.
> 8. State: status values match the specification, with no assumed statuses.
> 9. Pagination: cursor loops terminate.
> 10. Secrets and logging: no keys, JWTs, or signatures in logs.
>
> Output a table with severity, area, file and line, the issue, the failure scenario, and the fix. Put anything that can lose or duplicate money first, then add a short summary and list the areas you couldn't verify.
> ```

> [accordion] Prepare for Live
>
> Verifies readiness and produces a go/no-go report before you switch to Live.
>
> ```text theme={"theme":{"light":"poimandres","dark":"poimandres"}}
> We are about to switch our OpenFX v3 integration from Sandbox to Live. Verify that we are ready and produce a go/no-go report.
>
> Read first: https://docs.openfx.com/v3/live-checklist, https://docs.openfx.com/v3/environments, https://docs.openfx.com/v3/rate-limiting, and https://docs.openfx.com/v3/webhooks/setup.
>
> Check the codebase and configuration against every item on the Live checklist, and ask me for anything you can't check yourself. Don't read or print any key or secret value.
>
> Output a checklist with PASS, FAIL, or UNVERIFIED for each item with evidence, blocking items first, and a first-day Live test plan that uses small amounts.
> ```

## Verify what the agent built

An agent can produce code that looks correct and still fails on the first Live request. Before you rely on it:

1. Run the integration against Sandbox and confirm it completes a trade or a payout end to end.
2. Review the signing helper against [Authentication](https://public-openfx.mintlify.site/v3/authentication.md).
3. Confirm every write sends an `Idempotency-Key` that is stored before the request.
4. Confirm webhook handlers verify the signature on the raw body.
5. Work through the [Live checklist](https://public-openfx.mintlify.site/v3/live-checklist.md) before you switch to a Live key.

## What's next

> [card] [MCP connectors](https://public-openfx.mintlify.site/v3/mcp-connectors.md)
>
> Query your account data from an AI app.

> [card] [Live checklist](https://public-openfx.mintlify.site/v3/live-checklist.md)
>
> Review the full pre-launch checklist.
