> ## 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.

# Build with AI

> Use Claude, ChatGPT, Cursor, or your own coding agent to build an OpenFX v3 integration in Sandbox, or to ask about your account.

Build with AI

Bring Claude, ChatGPT, Cursor, or your own agent into your OpenFX work. Build your integration in Sandbox, or ask about your trades.

[Copy the starter prompt](#start-with-one-prompt)

[Claude](https://claude.ai/new?q=Read%20the%20OpenFX%20API%20docs%20at%20https%3A%2F%2Fdocs.openfx.com%2Fllms.txt%20and%20help%20me%20integrate%20with%20the%20OpenFX%20v3%20API.%20Start%20by%20asking%20what%20I%20want%20to%20build%20%28FX%20trades%2C%20payouts%2C%20deposits%2C%20withdrawals%2C%20or%20webhooks%29%20and%20which%20language%20I%20use.%20Start%20with%20Sandbox%20%28X-App-Mode%3A%20SANDBOX%29%20and%20keep%20the%20key%20and%20X-App-Mode%20in%20configuration%20so%20going%20live%20is%20a%20configuration%20change.%20Never%20ask%20me%20to%20paste%20a%20Live%20key%20or%20private%20key%2C%20and%20cite%20the%20docs%20page%20for%20every%20endpoint%20you%20use.)

[ChatGPT](https://chatgpt.com/?q=Read%20the%20OpenFX%20API%20docs%20at%20https%3A%2F%2Fdocs.openfx.com%2Fllms.txt%20and%20help%20me%20integrate%20with%20the%20OpenFX%20v3%20API.%20Start%20by%20asking%20what%20I%20want%20to%20build%20%28FX%20trades%2C%20payouts%2C%20deposits%2C%20withdrawals%2C%20or%20webhooks%29%20and%20which%20language%20I%20use.%20Start%20with%20Sandbox%20%28X-App-Mode%3A%20SANDBOX%29%20and%20keep%20the%20key%20and%20X-App-Mode%20in%20configuration%20so%20going%20live%20is%20a%20configuration%20change.%20Never%20ask%20me%20to%20paste%20a%20Live%20key%20or%20private%20key%2C%20and%20cite%20the%20docs%20page%20for%20every%20endpoint%20you%20use.)

[Cursor](https://cursor.com/link/prompt?text=Read%20the%20OpenFX%20API%20docs%20at%20https%3A%2F%2Fdocs.openfx.com%2Fllms.txt%20and%20help%20me%20integrate%20with%20the%20OpenFX%20v3%20API.%20Start%20by%20asking%20what%20I%20want%20to%20build%20%28FX%20trades%2C%20payouts%2C%20deposits%2C%20withdrawals%2C%20or%20webhooks%29%20and%20which%20language%20I%20use.%20Start%20with%20Sandbox%20%28X-App-Mode%3A%20SANDBOX%29%20and%20keep%20the%20key%20and%20X-App-Mode%20in%20configuration%20so%20going%20live%20is%20a%20configuration%20change.%20Never%20ask%20me%20to%20paste%20a%20Live%20key%20or%20private%20key%2C%20and%20cite%20the%20docs%20page%20for%20every%20endpoint%20you%20use.)

Just want to ask about your account? [Connect an AI app](#ask-your-agent-about-your-account) →

![Two hands drawn in dollar signs reaching toward each other](https://public-assets.openfx.com/docs/images/build-with-ai/banner-art.png)

## Start with one prompt

Paste this into any AI assistant. It reads the docs index first, asks what you're building, and keeps you in Sandbox.

```text wrap 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.
```

## Add the right files to your repo

Head off common integration mistakes, like reusing a JWT or sending amounts as floats.

your-project/

AGENTS.md
Start here


CLAUDE.md


SKILL.md

hosted by OpenFX

llms.txt

llms-full.txt

openapi.json

your-project/AGENTS.md
Download
Copy

`AGENTS.md` covers Sandbox, authentication, amounts, idempotency, errors, and webhooks. Codex, Cursor, and GitHub Copilot read it directly. Claude Code reads it through `CLAUDE.md` and the skill.

```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.
```

your-project/CLAUDE.md
Download
Copy

Claude Code reads `CLAUDE.md`, not `AGENTS.md`. If your repository doesn't already have a `CLAUDE.md`, create one that contains this single line so Claude Code loads the same rules.

```text CLAUDE.md theme={"theme":{"light":"poimandres","dark":"poimandres"}}
@AGENTS.md
```

your-project/.claude/skills/openfx-integration/SKILL.md
Download
Copy

A skill packages a repeatable workflow that Claude Code loads when a request matches its description. It sends the agent to `AGENTS.md` 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.
```

[https://docs.openfx.com/llms.txt](https://docs.openfx.com/llms.txt)
[Open](https://docs.openfx.com/llms.txt)

An index of every documentation page. Coding agents read the index first, then the pages for your task.

```text llms.txt theme={"theme":{"light":"poimandres","dark":"poimandres"}}
# OpenFX

> OpenFX API documentation. Real-time cross-border FX and stablecoin payment infrastructure.

- [Introduction](https://docs.openfx.com/v3/introduction.md): OpenFX gives financial institutions programmatic access to FX and stablecoin liquidity, plus payouts to bank accounts, with a consistent `{ data }` response envelope, stable error codes, and cursor pagination.
- [Quickstart](https://docs.openfx.com/v3/quickstart.md): Get from zero to your first executed trade in under 5 minutes.
- [Cheat sheet](https://docs.openfx.com/v3/cheat-sheet.md): Every endpoint at a glance. Method, path, auth, idempotency, pagination, response shape.
- [Glossary](https://docs.openfx.com/v3/glossary.md): Definitions for the vocabulary: resources, headers, status enums, and concepts used across the spec.
- [Build with AI](https://docs.openfx.com/v3/build-with-ai.md): Use Claude, ChatGPT, Cursor, or your own coding agent to build an OpenFX v3 integration in Sandbox, or to ask about your account.
- [Coding agents](https://docs.openfx.com/v3/coding-agents.md): Give your coding agent the OpenFX v3 rules, docs, and task prompts so it builds a correct integration in any language.
- [MCP connectors](https://docs.openfx.com/v3/mcp-connectors.md): Connect Claude, ChatGPT, Claude Code, or Codex to your OpenFX account to query trades, deposits, and withdrawals in plain language.
- [Trades](https://docs.openfx.com/v3/trades.md): The trade state machine from execution to settlement or reversal: statuses, settlement windows, the settle and reverse actions, and the webhooks that report each change.
- [Currencies](https://docs.openfx.com/v3/currencies.md): Fiat and stablecoin currencies for FX trading, first-party withdrawals, and payout funding, with rails, networks, and early-access labels.
- [Quotes](https://docs.openfx.com/v3/quotes.md): Atomic FX trades: discover supported pairs, quote a rate, execute the trade against the quote.
- [Settlement models](https://docs.openfx.com/v3/settlement-models.md): Netted and Per-Trade settlement models, plus the balances, deposits, and withdrawals flows they share.
- [Balances](https://docs.openfx.com/v3/balances.md): How to read the balances response: the org-wide aggregate, the per-currency rows, and what moves each amount.
- [Exposure](https://docs.openfx.com/v3/exposure.md): The organization's exposure-limit usage: how much is committed to unsettled trades, and the breakdown by currency and settlement stage.
- [Verified accounts](https://docs.openfx.com/v3/verified-accounts.md): Pre-configure your bank accounts and stablecoin wallets so withdrawals only need an `withdrawalAccountId` and a `withdrawalAmount`.
- [Deposits](https://docs.openfx.com/v3/deposits.md): Deposit status values, detection mechanics per rail, and the reconciliation pattern for incoming funds.
- [Withdrawals](https://docs.openfx.com/v3/withdrawals.md): Settlement windows per rail, and how to track the time between submission and settlement: webhooks first, adaptive polling as a fallback.
```

[https://docs.openfx.com/llms-full.txt](https://docs.openfx.com/llms-full.txt)
[Open](https://docs.openfx.com/llms-full.txt)

The full documentation in one file, for chat assistants that can't open links. The file is large, so avoid it in coding agents.

```text llms-full.txt theme={"theme":{"light":"poimandres","dark":"poimandres"}}
# Account model
Source: https://docs.openfx.com/v3/account-model

The resources behind a payout, how they relate, and the statuses they share.

An `Account` is someone you send money to or on behalf of: who they are, and what they're set up
to do. It holds no money. This page covers the resources a payout uses, how they fit together, and
the statuses they share.

## The four resources

| Resource | Who it belongs to | What it is |
| - | - | - |
| `FinancialAccount` | You | A balance in one currency that funds your payouts. OpenFX creates these for you. |
| `Account` | The person or company you pay | Who they are, plus the capabilities (`AccountCapability`) they hold. You create it. |
| `PayoutAddress` | The person or company you pay | A bank account the money lands in. It belongs to one `Account`, through `accountId`, and an account can have several. You create it. |
| `Payout` | You | Money sent from one of your financial accounts to a payout address. |

**A payout links your side to theirs.** It debits `financialAccountId` and credits
`receiver.payoutAddressId`. You don't name the receiving account, because the address already
```

[https://api.openfx.com/v3/openapi.json](https://api.openfx.com/v3/openapi.json)
[Open](https://api.openfx.com/v3/openapi.json)

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

```text openapi.json theme={"theme":{"light":"poimandres","dark":"poimandres"}}
{
  "openapi": "3.1.0",
  "info": {
    "title": "OpenFX API v3",
    "description": "FX trading, accounts, and payments on the OpenFX v3 API.",
    "version": "3.0.0",
    "termsOfService": "https://www.openfx.com/terms-and-conditions",
    "contact": {
      "name": "OpenFX Support",
      "email": "support@mail.openfx.com",
      "url": "https://www.openfx.com"
    },
    "license": {
      "name": "Proprietary — © OpenFX. All rights reserved.",
      "url": "https://www.openfx.com/terms-and-conditions"
    }
  },
  "servers": [
    {
      "url": "https://api.openfx.com"
```

## Prompts for common tasks

With `AGENTS.md` in your repo, each prompt only has to describe the task. Select a task to copy its prompt.

[All prompts](https://public-openfx.mintlify.site/v3/coding-agents.md#prompt-library)

## Ask your agent about your account

Connect Claude, ChatGPT, Claude Code, or Codex to your OpenFX account. Ask about your trades, deposits, and withdrawals, and build reports from the answers, without an API key.

Try asking: “Show me all my trades from last month, grouped by currency pair, with total notional per pair.”

What the connector reads

Trade history

Deposit history

Withdrawal history

Withdrawal accounts

Currency pairs

> [!NOTE]
>
> An OpenFX admin switches on each AI app under **Organization > MCP Platforms**. See [MCP connectors](https://public-openfx.mintlify.site/v3/mcp-connectors.md) for more details.

[https://mcp.openfx.com/mcp](https://mcp.openfx.com/mcp)
[https://mcp-sandbox.openfx.com/mcp](https://mcp-sandbox.openfx.com/mcp)

Live

Sandbox

Copy
Copy

Claude
Add a custom connector with this URL, then sign in to OpenFX
[Claude setup steps](https://public-openfx.mintlify.site/v3/mcp-connectors.md#claude)

ChatGPT
Add OpenFX as a custom app with this URL, then sign in
[ChatGPT setup steps](https://public-openfx.mintlify.site/v3/mcp-connectors.md#chatgpt)

Claude Code
Run `claude mcp add` with this URL, then sign in from `/mcp`
[Claude Code setup steps](https://public-openfx.mintlify.site/v3/mcp-connectors.md#claude-code)

Codex
Run `codex mcp add` with this URL, then `codex mcp login`
[Codex setup steps](https://public-openfx.mintlify.site/v3/mcp-connectors.md#codex)
