Exchange Integration Guide

Current integration guide for exchanges, custodians, and wallet backends.

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

Onyx Markets data integration

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;

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

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

Bridge-assisted treasury movement

The supported user interface is Bridge to Onyx. 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 and the REST API Reference 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.