hogan-yuan · Oct 8, 2026
diff --git a/docs/en/docs/cli/forex/_category_.json b/docs/en/docs/cli/forex/_category_.json
@@ -0,0 +1 @@
+{ "label": "Forex", "icon": "arrow-left-right", "position": 12, "collapsed": true }
diff --git a/docs/en/docs/cli/forex/exchange.mdx b/docs/en/docs/cli/forex/exchange.mdx
@@ -0,0 +1,71 @@
+---
+title: 'currency exchange'
+sidebar_label: 'currency exchange'
+sidebar_position: 1
+---
+
+# longbridge forex
+
+Convert cash between two currencies inside your account, right from the terminal. The flow is three steps and asynchronous: **quote** a rate, **submit** the conversion against that quote, then **query** the order until it settles.
+
+These commands act on your account, so they require login; `submit-order` moves real money and prompts for confirmation unless you pass `--yes`.
+
+## Basic Usage
+
+```bash
+# Lock a rate and get a quote_id (give --amount or --target-amount)
+longbridge forex quote USD HKD --amount 1000
+```
+
+```
+| Field     | Value            |
+|-----------|------------------|
+| quote_id  | Q20260925000123  |
+| rate      | 7.7812           |
+| ccy_pair  | USD/HKD          |
+| expire_at | 1790000000000    |
+```
+
+## Examples
+
+### Quote a rate
+
+```bash
+# By the convert-out amount (the USD you spend)
+longbridge forex quote USD HKD --amount 1000
+# …or by the convert-in amount (the HKD you want to receive)
+longbridge forex quote USD HKD --target-amount 7800
+```
+
+`rate` is quoted on the standard currency pair (`1 BASE = rate QUOTE`, e.g. `USD/HKD`), independent of the direction you ask for. The quote is bound to you and valid for a short window (`expire_at` is a Unix-millisecond timestamp).
+
+### Submit a conversion
+
+```bash
+# Submit against the quote_id, with your own unique client order id
+longbridge forex submit-order Q20260925000123 my-order-0001
+# Skip the confirmation prompt (e.g. for scripting)
+longbridge forex submit-order Q20260925000123 my-order-0001 --yes
+```
+
+Submitting only means the order was **accepted** — the conversion completes asynchronously, so the command re-queries and prints the current order state. Reusing the same `client_order_id` never places a second order; on a timeout, query first and only re-quote + resubmit with the **same** id.
+
+### Query an order
+
+```bash
+longbridge forex order my-order-0001
+```
+
+```
+| Field       | Value   |
+|-------------|---------|
+| state       | 1       |
+| rate        | 7.7812  |
+| from_amount | 1000    |
+| to_amount   | 7781.2  |
+| fail_reason |         |
+```
+
+`state` is `0` processing (keep polling), `1` success, or `2` failed (frozen funds are returned). Poll no more often than every 2 seconds; most orders settle within a minute.
+
+> Add `--format json` to any command for the full machine-readable payload.
diff --git a/docs/en/docs/forex/_category_.json b/docs/en/docs/forex/_category_.json
@@ -0,0 +1,8 @@
+{
+  "label": "Forex",
+  "collapsible": true,
+  "collapsed": true,
+  "position": 4.6,
+  "link": null,
+  "icon": "arrow-left-right"
+}
diff --git a/docs/en/docs/forex/overview.mdx b/docs/en/docs/forex/overview.mdx
@@ -0,0 +1,57 @@
+---
+id: forex_overview
+title: Overview
+slug: forex-overview
+sidebar_position: 1
+---
+
+# Forex Overview
+
+The forex (currency exchange) channel lets you convert a balance from one
+currency into another. Conversion is asynchronous and follows three steps:
+
+1. **Get Quote** — call [Get Quote](./quote) to lock in an execution rate and
+   obtain a `quote_id`. The quote is bound to you and expires after a short
+   window.
+2. **Submit Order** — call [Submit Order](./submit) with that `quote_id` and
+   your own `client_order_id` to place the conversion. Acceptance is
+   acknowledged synchronously, but the conversion itself is processed
+   asynchronously.
+3. **Query Order** — poll [Query Order](./query) with the same
+   `client_order_id` until the order reaches a terminal state (success or
+   failed).
+
+<table>
+    <thead>
+    <tr>
+        <td>Type</td>
+        <td>Introduction</td>
+    </tr>
+    </thead>
+    <tbody>
+    <tr>
+        <td rowspan="3">Forex</td>
+        <td><a href="./quote">Get Quote</a></td>
+    </tr>
+    <tr>
+        <td><a href="./submit">Submit Order</a></td>
+    </tr>
+    <tr>
+        <td><a href="./query">Query Order</a></td>
+    </tr>
+    </tbody>
+</table>
+
+## Error Codes
+
+| Code   | Description                                                                 |
+| ------ | --------------------------------------------------------------------------- |
+| 603001 | Parameter error                                                             |
+| 603002 | Unsupported currency pair                                                    |
+| 603004 | Quote not found                                                             |
+| 603005 | Quote expired (re-quote)                                                     |
+| 603006 | Quote already used (re-quote)                                                |
+| 603007 | Insufficient convertible balance                                            |
+| 603008 | Unauthorized / no exchange permission / outside service hours               |
+| 603009 | Order not found                                                             |
+| 603010 | Service temporarily unavailable, retry later                                |
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		{ "label": "Forex", "icon": "arrow-left-right", "position": 12, "collapsed": true }