> For the complete documentation index, see [llms.txt](https://docs.onyx.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.onyx.org/developer-guide/exchange-integration.md).

# Exchange Integration Guide

This guide covers native Onyx deposits and withdrawals, DEX and market-data integration, and optional bridge-assisted treasury movement.

## Network identity

| Property       | Mainnet value                              |
| -------------- | ------------------------------------------ |
| Network        | Onyx Mainnet                               |
| Chain type     | EVM-compatible Layer 1 with aBFT consensus |
| Chain ID       | `327` (`0x147`)                            |
| Native coin    | XCN                                        |
| Address format | EVM `0x` addresses                         |
| HTTPS RPC      | `https://rpc.onyx.org`                     |
| Explorer       | `https://explorer.onyx.org`                |

## Supported Mainnet assets

| Asset | Representation  | Address                                      |                                        Decimals | User status           |
| ----- | --------------- | -------------------------------------------- | ----------------------------------------------: | --------------------- |
| XCN   | Native gas coin | None                                         | 18 through JSON-RPC; 8-decimal ledger precision | Supported             |
| WXCN  | Wrapped XCN     | `0x1a0Da75ADf091a69E7285e596bB27218D77E17a9` |                                              18 | Supported for DEX use |
| ETH   | Bridged ERC-20  | `0x9253587505c3B7E7b9DEE118AE1AcB53eEC0E4b6` |                                              18 | Supported             |
| USDC  | Bridged ERC-20  | `0xC8410270bb53f6c99A2EFe6eD3686a8630Efe22B` |                                               6 | Supported             |

Verify addresses against the [contract registry](/reference/contracts.md) and `eth_getCode` before enabling an asset. Do not infer support merely because a contract exists or an API returns metadata.

## Deposit processing

* Poll `eth_blockNumber` and `eth_getBlockByNumber`, or subscribe to new heads.
* Detect native XCN transfers and ERC-20 `Transfer` logs.
* Reconcile credited deposits against balances and explorer/mirror data.
* Define your own risk-based crediting policy. Onyx consensus provides finality, but integrations must still account for RPC, indexing, and operational delay rather than promising a fixed confirmation time.
* A memo or destination tag is not part of the EVM address model; exchanges should issue a controlled address or use their normal EVM attribution design.

## Withdrawals

1. Query `eth_getTransactionCount` using the nonce policy used by your signer.
2. Align native XCN to a multiple of `10^10` RPC units.
3. Query `eth_gasPrice`.
4. Call `eth_estimateGas`; never assume a fresh address costs `21,000` gas.
5. Sign with Chain ID `327`, submit through `eth_sendRawTransaction`, and wait for a successful receipt.
6. Reconcile the post-transaction balance independently.

## DEX and swap integration

The Onyx App provides swaps through a deployed Uniswap V2-style factory and router. The currently active public execution markets are **XCN/USDC** and **ETH/USDC**. XCN is wrapped as WXCN inside liquidity pools.

| Contract      | Address                                      |
| ------------- | -------------------------------------------- |
| WXCN          | `0x1a0Da75ADf091a69E7285e596bB27218D77E17a9` |
| Factory       | `0x008c99EedA17E193e5F788536234C6b3520B8D15` |
| Router        | `0xa973c5626eEaF7F482439753953e9B28C6aF3674` |
| XCN/USDC pair | `0x57541cC904E863d6CBEe5Dbe5F55aCA799BC0e9F` |
| ETH/USDC pair | `0x6dc9C9E36a19a57A6cbe9E724a74bD4d98D2EE12` |

### Integration rules

* Discover active markets from live data rather than hardcoding pair lists.
* Verify token addresses, decimals, and bytecode before enabling a market.
* Review allowance, router path, expected output, and slippage in the signed transaction.
* A token appearing in metadata does not prove it is supported for trading or bridging; use active market classification and the [contract registry](/reference/contracts.md).

## Onyx Markets data integration

[markets.onyx.org](https://markets.onyx.org) is the public Onyx market-data surface. It provides:

* user-facing pages for assets and DEX markets;
* current prices, depth, liquidity, volume, and recent trade activity;
* transaction-linked trade and liquidity activity where available;
* public [OpenAPI documentation](https://markets.onyx.org/docs);
* CoinGecko- and CoinMarketCap-compatible market-data endpoints;
* Onyx and Ethereum staking data, plus Onyx governance data;
* liveness, readiness, freshness, and public status endpoints.

### Discovery and freshness

Use `/api/v1/execution-markets/` to discover active markets and `/api/v1/status/` to check indexer/calculator freshness. Do not hardcode prices, liquidity, APR, trade timestamps, or health from an example response.

```bash
curl -sS https://markets.onyx.org/api/v1/execution-markets/ | jq .
curl -sS https://markets.onyx.org/api/v1/status/ | jq .
```

Inspect the live [OpenAPI specification](https://markets.onyx.org/docs) for the complete path list and response schemas. Handle unknown fields and statuses defensively.

## Liquid staking data integration

Users stake native XCN through `StakedXCNDirect` and receive stXCN position accounting. Rewards accrue according to the contract's current index and parameters.

| Contract                | Address                                      |
| ----------------------- | -------------------------------------------- |
| StakedXCNDirect / stXCN | `0xA553a603e2f84fEa6c1fc225E0945FE176C72F74` |

Read current APR, fee, supply, backing, pause state, and timestamp from:

```
https://markets.onyx.org/api/staking/v1/onyx/stxcn
```

Use the response timestamp and freshness fields. The reward rate and protocol fee can be changed by the contract owner, and the contract can be paused or upgraded. Published APR is an estimate, not a guarantee.

For the user-facing staking flow, see [Staking and stXCN](/onyx-defi/onyx-app/staking.md).

## Bridge-assisted treasury movement

The supported user interface is [Bridge to Onyx](https://app.onyx.org/bridge). The deployed REST API is available through the app proxy:

```
https://app.onyx.org/api/bridge-proxy/api/v1
```

The bridge supports XCN, ETH, and USDC between Ethereum Mainnet and Onyx Mainnet. Fetch `/bridge/limits` and a fee quote at transaction time; fees, minimums, maintenance state, and processing time are mutable. Poll `/bridge/status` for the operation lifecycle. Native-XCN withdrawals use a signed intent and must use the relayer destination returned by the intent response rather than a hardcoded wallet.

See [Bridge Integration](/developer-guide/bridge.md) and the [REST API Reference](/developer-guide/bridge/api-reference.md) for endpoint details, smart-account requirements, and status handling.

## Integration checklist

* [ ] `eth_chainId` is pinned to `0x147`.
* [ ] Native XCN accounting preserves 8-decimal ledger precision.
* [ ] Gas and nonce handling were tested with both existing and new destination accounts.
* [ ] Deposits are reconciled through an independent data source.
* [ ] Every enabled ERC-20 has verified bytecode, symbol, decimals, and support status.
* [ ] Active DEX markets, prices, and liquidity are read from live Markets APIs rather than copied from documentation.
* [ ] Bridge limits and health are read live rather than copied from documentation.
* [ ] The complete flow was rehearsed on Testnet, followed by a controlled Mainnet canary.

Public endpoint capacity is shared and may change. Contact the Onyx team before depending on an assumed rate limit or service-level agreement.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.onyx.org/developer-guide/exchange-integration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.