Exchange Integration Guide

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

Network identity

Supported Mainnet assets

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.

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.

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.