docs: update README and add bilingual configuration guides for exchanges

- Changed installation command from `npx` to `bunx` for consistency. - Added bilingual configuration guides for Aster and Backpack exchanges. - Updated exchange details in the README to reflect new market types and required settings. - Enhanced clarity in the supported exchanges section with updated variable names and descriptions.
2026-09-11 01:08:07 +00:00 · 2026-07-12 11:51:45 +08:00
parent 35653c8beb
commit a6394191d8
20 changed files with 1669 additions and 238 deletions
@@ -0,0 +1,97 @@
+# Ondo Perps Configuration Guide
+
+中文版：[Ondo Perps 配置教程](ondoperps.md)
+
+## Scope
+
+This guide configures the Ondo Perps crypto, equity, and commodity perpetual adapter. Authentication uses an API key ID and an API secret with HMAC-SHA256 signatures.
+
+## 1. Create an API key
+
+1. Activate and fund an account on [Ondo Perps](https://app.ondoperps.xyz/?ref=4A3ACQ).
+2. Create an API key with read and trading permissions from the account API settings.
+3. Save the API key ID and API secret.
+4. Keep withdrawal access disabled and add a fixed IPv4 whitelist.
+
+## 2. Minimal mainnet configuration
+
+```dotenv
+EXCHANGE=ondoperps
+ONDOPERPS_API_KEY_ID=<your_ondo_key_id>
+ONDOPERPS_API_SECRET=<your_ondo_api_secret>
+ONDOPERPS_SYMBOL=BTC-USD.P
+```
+
+Market symbols use the `{TICKER}-USD.P` format, including:
+
+- `BTC-USD.P`
+- `ETH-USD.P`
+- `XAU-USD.P`
+- `NVDA-USD.P`
+
+The adapter also normalizes `BTCUSDT`, `BTC/USD`, and `BTC-USD` to `BTC-USD.P`.
+
+## 3. Sandbox configuration
+
+```dotenv
+EXCHANGE=ondoperps
+ONDOPERPS_SANDBOX=true
+ONDOPERPS_API_KEY_ID=<your_sandbox_key_id>
+ONDOPERPS_API_SECRET=<your_sandbox_api_secret>
+ONDOPERPS_SYMBOL=BTC-USD.P
+```
+
+Sandbox mode defaults to:
+
+- REST: `https://api.ondoperps-sandbox.xyz`
+- WebSocket: `wss://api.ondoperps-sandbox.xyz/ws`
+
+The sandbox requires separately generated credentials.
+
+## 4. Optional settings
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `ONDOPERPS_BASE_URL` | `https://api.ondoperps.xyz` | REST API base URL |
+| `ONDOPERPS_WS_URL` | `wss://api.ondoperps.xyz/ws` | WebSocket URL |
+| `ONDOPERPS_BUILDER_CODE` | Empty | Builder code assigned by Ondo |
+| `ONDOPERPS_BUILDER_FEE_RATE_BPS` | Empty | Positive integer builder fee, capped at 10 bps by the adapter |
+
+Compatibility aliases:
+
+- `EXCHANGE=ondoperp` or `EXCHANGE=ondo`
+- Legacy `ONDOPERP_*` variable prefix
+- `ONDO_KEY_ID` and `ONDO_API_SECRET`
+
+Use `ondoperps` and `ONDOPERPS_*` for new deployments.
+
+## 5. Verify the configuration
+
+```bash
+bun run index.ts doctor --exchange ondoperps --symbol BTC-USD.P --json
+bun run index.ts market ticker --exchange ondoperps --symbol BTC-USD.P --json
+```
+
+The ticker check loads contract precision, opens WebSocket connections, and performs read-only market requests. It creates no orders.
+
+## Troubleshooting
+
+- `Missing ONDOPERPS_API_KEY_ID or ONDOPERPS_API_SECRET`: provide the complete credential pair.
+- `401` or signature failures: synchronize system time and verify the key ID, secret, environment, and IP whitelist.
+- Missing market: use a `{TICKER}-USD.P` symbol from the official Ondo market list.
+- Invalid builder fee: use an integer from `1` to `10` bps.
+- Empty production account in sandbox: use the dedicated sandbox account and credentials.
+
+## Security
+
+- Grant read and trading permissions only.
+- Pass the API secret through the local runtime environment.
+- Revoke and replace the key immediately after exposure.
+
+## References
+
+- [Ondo Perps API Authentication](https://docs.ondoperps.xyz/api-reference/api_key_authentication.md)
+- [Ondo Perps REST Specification](https://docs.ondoperps.xyz/api-reference/rest-spec.json)
+- [Ondo Perps WebSocket Specification](https://docs.ondoperps.xyz/api-reference/ws-spec.json)
+- [Repository Ondo Perps integration reference](../ondoperps/README.md)
+