# Welcome to Onyx Current user and developer documentation for Onyx Mainnet. ## Blockchain Built for Real-World Finance Onyx is a high-performance Layer 1 blockchain designed for payments, financial institutions, and real-world applications. It combines EVM compatibility with asynchronous Byzantine fault tolerant (aBFT) consensus, giving builders familiar smart-contract tooling on a network built for practical financial activity. {% hint style="success" %} **Your simplest first step:** [Bridge USDC, ETH, or XCN to Onyx](https://app.onyx.org/bridge). {% endhint %} ## Put your assets to work * **Earn 30.00% APR with Onyx Liquid Staking.** Stake XCN and receive liquid stXCN. The rate is variable; check the live app before confirming. * **Bridge USDC, ETH, or XCN to Onyx.** Move supported assets from Ethereum into the Onyx economy. * **Trade XCN, USDC, and ETH.** Access active Onyx markets from the app, with more assets coming. * **Farm XCN rewards.** Add liquidity to the XCN/USDC pair, then stake the LP tokens in Farms. ## Start here | Goal | Resource | | -------------------------------------- | ------------------------------------------------------------------- | | Bridge to Onyx | [Bridge USDC, ETH, or XCN to Onyx](https://app.onyx.org/bridge) | | Swap, stake, farm, or migrate | [Onyx App](https://app.onyx.org) | | View transactions and contracts | [Onyx Explorer](https://explorer.onyx.org) | | Review DEX markets, activity, and APIs | [Onyx Markets](https://markets.onyx.org) | | Add Mainnet to a wallet | [Quick Start](/readme/quick-start) | | Build on Chain 327 | [Developer Guide](/developer-guide/getting-started) | | Integrate deposits and withdrawals | [Exchange Integration Guide](/developer-guide/exchange-integration) | # About Onyx What Onyx Mainnet is and how its public interfaces fit together. Onyx is an EVM-compatible Layer 1 network. Applications use familiar Ethereum addresses, Solidity contracts, signed EVM transactions, and JSON-RPC methods, while the underlying ledger reaches aBFT consensus. The public data path is: ``` consensus validators -> signed record streams -> regional mirror services -> REST/gRPC data services and EVM JSON-RPC relays -> wallets, explorers, applications, and indexers ``` This is not a rollup or Layer 3. Onyx does not depend on another chain for transaction ordering or settlement. # Chain Info Verified Onyx Mainnet and Testnet connection details. ## Onyx Mainnet | Field | Value | | --------------------------- | ---------------------------------------------------------------------- | | Network | Onyx Mainnet | | Chain ID | `327` (`0x147`) | | Native currency | XCN | | Wallet/RPC display decimals | `18` | | HTTPS RPC | `https://rpc.onyx.org` | | Explorer | `https://explorer.onyx.org` | | Validator dashboard | `https://validators.onyx.org` | | Network fees | [Current gas price and fee calculation](/developer-guide/network-fees) | ## Onyx Testnet | Field | Value | | --------------- | ----------------- | | Chain ID | `8901` (`0x22c5`) | | Native currency | Testnet XCN | Testnet assets have no Mainnet value. Testnet availability and access details can change; never send Mainnet assets to Testnet contracts or addresses based only on a matching label. # Quick Start Add Onyx Mainnet to a wallet and make a safe first transaction. ## Add Onyx Mainnet The fastest way to add Onyx to MetaMask or another EVM wallet is from the [Onyx Explorer](https://explorer.onyx.org): open the explorer and use the **Add Onyx Network** control in the bottom-left corner for a one-click wallet prompt. You can also enter the network details manually: | Setting | Value | | --------------- | --------------------------- | | Network name | Onyx Mainnet | | RPC URL | `https://rpc.onyx.org` | | Chain ID | `327` | | Currency symbol | `XCN` | | Explorer | | For dApp / programmatic wallet setup (`wallet_addEthereumChain`) and RPC `eth_chainId` verification, see [Developer Guide → Getting Started](/developer-guide/getting-started). ## Important transaction rules * XCN is represented with 18 decimals through JSON-RPC, but the native ledger has 8-decimal precision. See [XCN Decimal Handling](/developer-guide/decimal-handling). * A transfer to a new address can require substantially more gas because the account is created on first receipt. Always use `eth_estimateGas`; never hardcode `21,000`. See [Lazy Account Creation](/developer-guide/lazy-create-gas). * Read `eth_gasPrice` when preparing a transaction and handle RPC errors instead of assuming Ethereum Mainnet fee-market behavior. See [Network Fees](/developer-guide/network-fees) for the current snapshot, calculation, and USD denomination. # About XCN XCN is the native coin of Onyx Mainnet and pays for gas and native transfers. It also exists as an ERC-20 on Ethereum Mainnet and participates in Onyx Protocol governance and ecosystem applications. Onyx Mainnet is an EVM-compatible Layer 1. The Ethereum and native Onyx representations can be moved through the supported [Onyx Bridge](/onyx-defi/onyx-app/bridge). # Token Supply XCN supply changes through documented issuance, burns, and cross-chain representation. A fixed snapshot becomes stale quickly, so this page does not publish a current total. Use the Ethereum token contract, Onyx explorer/mirror data, and [Markets supply endpoints](https://markets.onyx.org/docs) for time-stamped values. Keep native Onyx circulation separate from bridge backing when reconciling representations. # Token Distribution Token distribution changes as vesting, treasury, governance, bridge, staking, and market balances move. Use current on-chain holder and contract data rather than a distribution chart copied from an earlier date. For production accounting, define the exact contract set and timestamp used by the calculation and reconcile Ethereum XCN with native Onyx and bridge balances. # Utility and Governance XCN is used as: * the native gas and transfer asset on Onyx Mainnet; * the asset deposited into [Onyx liquid staking](/onyx-defi/onyx-app/staking); * an asset in supported [Onyx DEX](/onyx-defi/onyx-app/markets) and [Onyx Bridge](/onyx-defi/onyx-app/bridge) flows; * a governance and ecosystem token where the relevant application and contracts enable it. Governance scope and eligibility depend on the specific deployed governance system. Verify the active UI, chain, contract, and proposal state before acting. # MiCA Whitepaper You can access the MiCA whitepaper by following the provided link below. The document, titled “MiCA Whitepaper,” serves as a comprehensive guide to the Markets in Crypto-Assets (MiCA) regulation, outlining its objectives, framework, and implications for the cryptocurrency and digital asset sectors. Access the MiCA whitepaper [here](https://onyx.org/MiCA.pdf). # Getting Started Connect EVM tooling to Onyx Mainnet safely. Onyx Mainnet accepts signed EVM transactions through JSON-RPC on Chain ID `327`. ```javascript import { JsonRpcProvider } from "ethers"; const provider = new JsonRpcProvider("https://rpc.onyx.org", 327); const network = await provider.getNetwork(); if (network.chainId !== 327n) throw new Error("Wrong network"); console.log(await provider.getBlockNumber()); ``` ## Mainnet endpoints | Service | URL | | ------------------- | --------------------------- | | JSON-RPC | `https://rpc.onyx.org` | | Explorer | | | Markets and OpenAPI | `https://markets.onyx.org` | End users can also add Onyx with one click from the [Onyx Explorer](https://explorer.onyx.org) (bottom-left **Add Onyx Network** button). See [Quick Start](/readme/quick-start). ## Add Onyx programmatically For wallet dApps and browser providers, request the chain with EIP-3085: ```javascript await window.ethereum.request({ method: "wallet_addEthereumChain", params: [{ chainId: "0x147", chainName: "Onyx Mainnet", nativeCurrency: { name: "XCN", symbol: "XCN", decimals: 18 }, rpcUrls: ["https://rpc.onyx.org"], blockExplorerUrls: ["https://explorer.onyx.org"] }] }); ``` Verify the network before signing: ```bash curl -sS https://rpc.onyx.org \ -H 'content-type: application/json' \ --data '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}' ``` The result must be `0x147` (decimal `327`). ## Before sending value 1. Verify `eth_chainId` returns `0x147`. 2. Use `eth_estimateGas` for every transaction, especially transfers to unused addresses. 3. Use the gas price returned by the RPC. See [Network Fees](/developer-guide/network-fees) for the current snapshot, calculation, and USD denomination. 4. Keep native XCN values aligned to the ledger's 8-decimal precision. 5. Wait for a successful transaction receipt and reconcile balances through an independent read path. Onyx supports the commonly used EVM read, transaction, contract-call, log, and subscription methods documented in [EVM JSON-RPC](/apis/evm-json-rpc). It does not claim complete parity with every Ethereum client extension. # Network Fees Understand how Onyx network fees are priced, calculated, and converted between XCN and USD. Onyx network fees are paid in native **XCN**. The network assigns USD-denominated costs to transaction resources, converts those costs into XCN using the current network conversion rate, and exposes wallet-compatible gas values through JSON-RPC. The XCN amount can change as the conversion rate changes, even when the intended USD cost is broadly stable. Always obtain a fresh gas estimate and gas price immediately before signing. This page focuses on EVM transactions submitted through the public JSON-RPC endpoint. Native service transactions can include additional resource-based charges; use the final transaction record or explorer entry for the amount actually charged. ## Current fee snapshot The following values were verified against Onyx Mainnet on **July 21, 2026 at 19:38 UTC**: | Item | Current value | | ------------------------------------ | ----------------------------: | | Wallet gas price from `eth_gasPrice` | **620 Gwei** (`0x905ae13800`) | | Wallet gas price in native units | **62 tinyXCN per gas** | | Wallet gas price in XCN | **0.00000062 XCN per gas** | | Network conversion rate | **$0.00477 per XCN** | | Approximate USD cost per gas | **$0.0000000029574** | The raw EVM network fee estimate was **54 tinyXCN per gas** at the same snapshot. The public RPC gas price included the network's current 15% safety margin and rounded the result to 62 tinyXCN. This margin helps prevent a transaction from becoming underpriced if the XCN conversion changes between estimation and submission. At this snapshot, the wallet-facing calculation was: ``` raw network price = 54 tinyXCN per gas safety margin = round(54 x 15%) = 8 tinyXCN per gas wallet gas price = 54 + 8 = 62 tinyXCN per gas ``` These are dated values, not permanent constants. Query the live RPC before every transaction. ## How the fee is calculated For an executed EVM transaction: ``` network fee in XCN = gas used x effective gas price / 10^18 network fee in USD = network fee in XCN x current USD-per-XCN conversion rate ``` The gas limit is a maximum execution allowance, not necessarily the amount charged: ``` maximum gas budget = gas limit x maximum fee per gas final execution charge = gas used x effective gas price ``` Unused gas is not charged. A reverted or otherwise unsuccessful transaction can still consume gas and incur a fee for the work performed. ### Example costs at the current snapshot | Gas used | Fee in XCN | Approximate fee in USD | | -------: | ----------: | ---------------------: | | 21,000 | 0.01302 XCN | $0.0000621 | | 100,000 | 0.062 XCN | $0.000296 | | 800,000 | 0.496 XCN | $0.00237 | A transfer to an existing account may use 21,000 gas. A transfer that creates its destination account can require substantially more. Use the actual transaction with `eth_estimateGas`; do not select a gas limit from this table. See [Lazy Account Creation](/developer-guide/lazy-create-gas). ## XCN, tinyXCN, Gwei, and USD Native XCN settles at 8-decimal ledger precision while EVM JSON-RPC uses 18-decimal wallet units: ``` 1 XCN = 100,000,000 tinyXCN 1 tinyXCN = 10,000,000,000 EVM wallet units = 10 Gwei 620 Gwei = 62 tinyXCN = 0.00000062 XCN ``` For the snapshot above, the network conversion rate represented **30,000 XCN as 14,310 cents**, or: ``` $143.10 / 30,000 XCN = $0.00477 per XCN ``` USD figures are estimates for understanding the network's fee denomination. The transaction is charged in XCN, not USD, and a wallet or exchange may display a different market conversion. ## Obtain the live values Read the wallet-facing gas price from the public RPC: ```bash curl -sS https://rpc.onyx.org \ -H 'content-type: application/json' \ --data '{"jsonrpc":"2.0","method":"eth_gasPrice","params":[],"id":1}' ``` Read the current network conversion rate and raw EVM fee schedule: ```bash curl -sS https://api.onyx.org/api/v1/network/exchangerate curl -sS https://api.onyx.org/api/v1/network/fees ``` Applications should use `eth_estimateGas` for gas units and `eth_gasPrice` for the wallet-facing price. Onyx does not currently use Ethereum's dynamic congestion base fee: `baseFeePerGas` is zero, while `eth_maxPriorityFeePerGas` returns the same current value as `eth_gasPrice`. Do not copy fee settings from another network. ## Network fees versus application fees Network gas is separate from fees charged by an application or protocol: * **Bridge fees** are quoted by the bridge and can vary by asset and direction. * **Swap fees and price impact** are determined by the selected liquidity pool and trade. * **Staking protocol fees** are governed by the staking contract's current parameters. A transaction can include both a network fee and an application-level fee. Review both before confirming. # 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](/reference/contracts) 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). ## 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). ## 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) and the [REST API Reference](/developer-guide/bridge/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. # XCN Decimal Handling Correctly convert native XCN between ledger and JSON-RPC units. Native XCN has two representations: | Context | Precision | | ------------- | ------------------------------------------ | | Native ledger | 8 decimals (`1 XCN = 100,000,000 tinyxcn`) | | EVM JSON-RPC | 18-decimal wei-style integers | One `tinyxcn` therefore equals `10^10` JSON-RPC units. Native XCN values sent through JSON-RPC must be a multiple of `10^10`. ```javascript const RPC_UNITS_PER_TINYXCN = 10n ** 10n; function alignNativeXcn(value) { return value - (value % RPC_UNITS_PER_TINYXCN); } ``` This rule applies to native XCN only. ERC-20 tokens use the value returned by their own `decimals()` function. Current examples include WXCN and bridged ETH with 18 decimals, bridged USDC with 6, and stXCN with 18. Do not use JavaScript `BigInt` directly in protobuf-js `int64` fields. For native SDK code, use the integer type required by that SDK and keep the unit conversion explicit. # Lazy Account Creation Estimate gas correctly when a transfer creates its destination account. An EVM address may not yet have a native ledger account. The first qualifying transfer to that address can create it, which costs more gas than a transfer to an existing account. Always call `eth_estimateGas` with the actual sender, recipient, value, and data. Do not hardcode `21,000` and do not permanently cache an estimate for an address. ```javascript const estimate = await provider.estimateGas({ from, to, value }); const gasLimit = (estimate * 120n) / 100n; ``` An estimate is state-dependent. Submit promptly, preserve a reasonable safety margin, and surface the RPC error if estimation fails. A syntactically valid vanity address is not necessarily backed by a usable ECDSA key; only send to an address the recipient controls. # Deploying Contracts Deploy and verify Solidity contracts on Onyx Mainnet. Use ordinary Solidity tooling with Chain ID `327`. Estimate gas and read the current gas price instead of pinning values copied from another network. ```javascript import "dotenv/config"; import { JsonRpcProvider, Wallet, ContractFactory } from "ethers"; import artifact from "./artifacts/Example.json" with { type: "json" }; const provider = new JsonRpcProvider("https://rpc.onyx.org", 327); const signer = new Wallet(process.env.DEPLOYER_PRIVATE_KEY, provider); const factory = new ContractFactory(artifact.abi, artifact.bytecode, signer); const contract = await factory.deploy(); await contract.waitForDeployment(); console.log(await contract.getAddress()); ``` Keep private keys out of source code and shell history. After deployment, confirm `eth_getCode` is non-empty and verify the source through the [Onyx Explorer](https://explorer.onyx.org). Onyx follows EVM execution semantics but is not required to expose every Ethereum client-specific debug or tracing extension. Test the exact RPC methods your deployment and verification pipeline needs before Mainnet use. # Bridge Integration Integrate the Onyx bridge without hardcoding mutable limits or operator addresses. The Onyx bridge moves XCN, ETH, and USDC between Ethereum Mainnet and Onyx Mainnet. | Interface | URL | | ------------------- | -------------------------------------------- | | User interface | `https://app.onyx.org/bridge` | | **REST API** | **`https://bridgeapi.onyx.org/api/v1`** | | Ethereum BridgeLock | `0xa9fd64b5095d626f5a3a67e6db7fb766345f8092` | | Onyx BridgeMint | `0x1d14ae13ca030eb5e9e2857e911af515cf5ffff2` | {% hint style="info" %} **External integrators** should call **`https://bridgeapi.onyx.org/api/v1`** directly. The first-party app may use a same-origin proxy under `app.onyx.org`; that path is optional for browser UIs and is **not** required for server-side or partner clients. {% endhint %} ## Integration rules * Call `GET /health` before enabling a bridge action. * Fetch `GET /bridge/limits` and a fee quote immediately before presenting or submitting a transfer. * Poll `GET /bridge/status` using the source transaction hash and surface the returned status truthfully. * Treat maintenance or delayed states as unavailable/in-progress, not as success. * For native XCN from Onyx to Ethereum, register the signed intent first and send only to the destination returned by that response. * ERC-1271 signatures from deployed smart accounts are supported. For ERC-4337, bind the final execution transaction hash, not the user-operation hash. Processing time depends on source-chain confirmation, relayer state, security holds, and destination submission. Applications must use API state instead of promising a fixed duration. See the [REST API Reference](/developer-guide/bridge/api-reference), [Smart Account Integration](/developer-guide/bridge/smart-account-integration), and [contract registry](/reference/contracts). # REST API Reference Public bridge REST endpoints and dynamic discovery rules. **Base URL (mainnet):** ``` https://bridgeapi.onyx.org/api/v1 ``` | Method and path | Purpose | | ---------------------------------------------- | ------------------------------------------------------------------- | | `GET /health` | Operational state and chain connectivity | | `GET /bridge/limits` | Current fee basis points, minimum amounts, and minimum fees | | `GET /bridge/fee-quote` | Quote the current output and fee for a direction, token, and amount | | `GET /bridge/status` | Track an operation by origin transaction hash or bridge identifier | | `GET /bridge/history` | Retrieve wallet bridge history | | `POST /bridge/xcn-withdraw-intent` | Register a signed native-XCN withdrawal intent | | `POST /bridge/xcn-withdraw-intent/bind-origin` | Bind an intent to its Onyx execution transaction | The exact request and response schemas are deployed behavior. Inspect responses in a non-production client and handle unknown fields or statuses defensively. ## Live discovery example ```bash curl -sS https://bridgeapi.onyx.org/api/v1/bridge/limits | jq . curl -sS https://bridgeapi.onyx.org/api/v1/health | jq '{status,operational,database}' ``` Never copy the returned fee or minimum into a long-lived build. Fetch again before a user confirms a transfer. ## Status handling Continue polling while the operation is non-terminal. Display the API's maintenance, confirmation, hold, retry, failure, and completion state without manufacturing a destination hash. A completed operation should include the destination proof expected by your integration before you credit or reconcile it. The native-XCN intent response contains the current transfer destination. It is an operator-controlled value and must not appear as a constant in application code or documentation. # Smart Account Integration ERC-1271 and ERC-4337 requirements for native-XCN bridge intents. Native-XCN withdrawal intents accept signatures from deployed ERC-1271 smart accounts. ## Requirements 1. `senderAddress` is the deployed smart-account contract on Onyx, not its owner EOA. 2. The contract must validate `isValidSignature(bytes32,bytes)` with the ERC-1271 magic value. 3. Register the intent before transferring XCN. 4. Read the transfer destination from the intent response every time. 5. Transfer the exact `amountAtomic` from the smart account to that destination. 6. For ERC-4337, resolve the user operation to its final execution transaction and bind that transaction hash. A `userOpHash` is not an Onyx transaction hash. Counterfactual or undeployed accounts and ERC-6492 wrapping are not documented as supported. Test the exact account implementation before enabling a production withdrawal path. # Network Architecture High-level deployed architecture of Onyx Mainnet. Onyx is an EVM-compatible Layer 1 secured by aBFT consensus. ``` Transactions -> public RPC/gRPC entry points -> consensus validators -> signed record streams -> regional mirror importers and databases -> Mirror REST/gRPC and JSON-RPC relays -> explorers, wallets, applications, and indexers ``` Consensus validators order transactions and produce the authoritative ledger record. Signed record streams feed regional mirror services, which provide query-oriented APIs and historical data. JSON-RPC relays translate EVM-facing requests and submit transactions through the network's native services. This separation explains an important operational property: a read API or explorer can lag even while consensus remains healthy. Applications should compare independent signals and avoid treating one endpoint as proof of the entire network state. Validator locations, private addresses, operator accounts, and deployment procedures are intentionally not published in user-facing documentation. # Onyx App Mainnet entry point for Onyx swap, bridge, staking, farming, and migration. [app.onyx.org](https://app.onyx.org) is the primary user interface for Onyx Mainnet. | Workflow | What it does | | ------------------------------------------------ | --------------------------------------------------------------------- | | [Swap and Markets](/onyx-defi/onyx-app/markets) | Trade active Onyx DEX pairs and inspect market data | | [Bridge](/onyx-defi/onyx-app/bridge) | Move supported assets between Ethereum and Onyx | | [Staking and stXCN](/onyx-defi/onyx-app/staking) | Stake native XCN and manage the liquid staking position | | [Farming](/onyx-defi/onyx-app/farming) | Add XCN/USDC liquidity and stake LP tokens to earn XCN rewards | | [Migrate to Onyx](/onyx-defi/onyx-app/migrate) | Move legacy Ethereum-staked XCN into Onyx, optionally auto-staking it | Always confirm the connected chain and transaction details in the wallet. Values shown by an interface can change between quote and submission; the signed transaction is authoritative. # Swap and Markets Trade on Onyx Mainnet swap markets. Use the [Onyx App](https://app.onyx.org) to swap on Onyx Mainnet. The active trading pairs are **XCN/USDC** and **ETH/USDC**. You can also review prices, liquidity, volume, and recent activity on [Onyx Markets](https://markets.onyx.org). ## Before you swap * Confirm you are connected to **Onyx Mainnet** (Chain ID 327). * Review the token, expected output, price impact, and slippage in your wallet before signing. * A token appearing elsewhere in the ecosystem does not mean it is supported for swapping. Use only the pairs available in the app. For DEX contracts, market-data APIs, and integration requirements, see the [Exchange Integration Guide](/developer-guide/exchange-integration). # Bridge Use the Mainnet bridge and interpret its live status correctly. Use [Bridge to Onyx](https://app.onyx.org/bridge) to move **XCN**, **ETH**, and **USDC** between Ethereum Mainnet and Onyx Mainnet. The bridge supports both directions. Fees, minimums, and processing times differ by direction. Always confirm current values in the app before you submit a transfer. ## Supported assets | Asset | Ethereum | Onyx | | -------- | ----------- | ------------------------------ | | **XCN** | ERC-20 XCN | Native XCN (gas and transfers) | | **ETH** | Native ETH | Bridged ETH (18 decimals) | | **USDC** | ERC-20 USDC | Bridged USDC (6 decimals) | All three assets can move in both directions when the bridge is operational. If an asset is unavailable in the app, treat it as unsupported regardless of what appears elsewhere in the ecosystem. ## Fees Bridge fees are application-level charges and are separate from Onyx network gas. They can include a percentage charge, a per-asset minimum fee, or both. Directional fees and minimum transfer amounts can change. Use the [Onyx Bridge](https://app.onyx.org/bridge) for the exact amount you will receive. Integrations must fetch the current limits and a live fee quote immediately before confirmation; documentation examples are not a source of truth for mutable bridge values. See [Network Fees](/developer-guide/network-fees) for transactions submitted on Onyx. Transactions submitted on Ethereum incur Ethereum network gas separately. ## Processing times and delays Bridge transfers are not instant. Each transfer moves through several phases: 1. **Source confirmation** — your transaction is confirmed on the sending chain. 2. **Security hold** (Onyx → Ethereum only) — withdrawals wait approximately **1 hour** before the relayer submits the Ethereum leg. 3. **Relay** — the bridge operator processes the transfer. 4. **Destination submission** — the receiving-chain transaction is broadcast. 5. **Completion** — funds arrive at your destination address. Total time depends on network congestion, relayer load, and the direction you are bridging. Track progress in the Bridge app. A successful source transaction does not mean the destination leg has finished. When bridge health is degraded, the app may enter maintenance mode and pause new transfers. Existing transfers can still be tracked — do not resubmit the same transfer. For bridge APIs, smart-account requirements, and integration details, see [Bridge Integration](/developer-guide/bridge). External integrators use **`https://bridgeapi.onyx.org/api/v1`**. # Staking and stXCN Stake XCN on Onyx Mainnet and understand stXCN rewards and risks. [Onyx liquid staking](https://app.onyx.org) lets you stake native XCN and receive **stXCN**, a liquid staking token that represents your staked position. ## How it works 1. Connect a wallet on Onyx Mainnet. 2. Stake XCN through the app. 3. Receive stXCN in return. 4. Hold, transfer, or use stXCN while your position earns rewards. Reward rates are variable and can change. Check the current APR in the app before you stake. ## Risks Staking involves smart-contract risk. The protocol owner can adjust reward rates, fees, pause staking, or upgrade contracts. APY is not guaranteed, and stXCN should not be treated as a fixed-return product. For staking contract addresses, live data APIs, and integration details, see the [Exchange Integration Guide](/developer-guide/exchange-integration). # Farming Add XCN/USDC liquidity and farm XCN rewards on Onyx. [Onyx Farms](https://app.onyx.org/en/farm) lets liquidity providers stake supported LP tokens to earn XCN rewards. ## XCN/USDC farming 1. Open [Farms](https://app.onyx.org/en/farm) and connect a wallet on Onyx Mainnet. 2. Choose the XCN/USDC farm and use **Add Liquidity** to supply both assets. 3. Stake the resulting LP tokens in the farm. 4. Monitor earned XCN and claim or unstake when appropriate. Farming rewards, allocation rates, token prices, and pool liquidity can change. Use the values shown by the live app when making a decision. Providing liquidity can lose value relative to simply holding the assets, and smart-contract risk remains. Review the transaction details and understand impermanent loss before depositing. For DEX contracts, LP pair addresses, and integration details, see the [Exchange Integration Guide](/developer-guide/exchange-integration). # Migrate to Onyx Move legacy Ethereum-staked XCN to Onyx with optional auto-staking. The [Migrate page](https://app.onyx.org/en/migrate) guides eligible users through the Ethereum-to-Onyx flow: 1. approve any required Ethereum XCN allowance; 2. withdraw or unstake from the legacy Ethereum staking position; 3. bridge the available XCN to Onyx; 4. optionally deliver it into Onyx liquid staking. Each wallet prompt is a separate authorization. Read the chain, contract, amount, and allowance before signing, and keep the page open while it waits for receipts and refreshes balances. ## Truthful fallback Auto-staking is an optional destination action, not a condition for preserving the bridge delivery. If the staking leg cannot complete, the system can deliver native XCN instead and record the staking error. The user can then stake manually through the Onyx App. Check the final asset balance and bridge status; do not infer stXCN delivery merely because the source bridge transaction succeeded. Bridge limits and health are dynamic. The app should prevent a transfer below the live minimum, but users should still review the final quote and status before proceeding. # Testnet DeFi and Slingshot Short guide to the Onyx Testnet Slingshot interface. Slingshot is the DeFi interface for Onyx Testnet, Chain ID `8901`. It is separate from Onyx Mainnet and is intended for testing. Current access details are announced through official Onyx channels. The interface exposes [Swap](/onyx-defi/testnet-defi/swap), [Bridge](/onyx-defi/testnet-defi/bridge), [Migrate](/onyx-defi/testnet-defi/migrate), and [Yield](/onyx-defi/testnet-defi/yield). Availability, liquidity, faucet delivery, and relayer operation are best-effort and can change without Mainnet guarantees. Testnet XCN and test tokens have no Mainnet value. Verify the wallet shows Chain ID `8901` before signing. # Swap Use the Slingshot Swap route on Onyx Testnet (`8901`). Token lists and liquidity are test fixtures and can be reset or withdrawn. Confirm the Testnet token address and do not use Mainnet pricing assumptions. # Bridge Use the Slingshot Bridge route for supported test transfers between Ethereum Sepolia and Onyx Testnet. Testnet relaying is best-effort, assets have no Mainnet value, and Mainnet bridge limits or addresses must not be reused here. # Migrate Use the Slingshot Migrate route to rehearse the Sepolia-to-Onyx Testnet migration flow. Inspect every wallet prompt, wait for both chains, and verify the final Testnet balance rather than assuming the destination action completed. # Yield Use the Slingshot Yield route to test liquid staking on Chain ID `8901`. Testnet rates, balances, and contracts are not Mainnet promises. Verify the current Testnet contract through official Onyx Testnet information before integrating. # Rewards Overview Distinguish Onyx liquid staking, protocol staking rewards, and validator rewards. Onyx uses several reward concepts that should not be combined: | Reward type | Recipient | Where to verify | | ------------------------------- | ---------------------------------------------------- | --------------------------------------------------- | | Liquid staking | stXCN holders | Onyx App and Markets staking API | | Protocol/native account staking | Eligible ledger accounts under current network rules | Network state and applicable protocol documentation | | Validator/node rewards | Eligible node operators | Validator dashboard and operator records | Liquid staking is a smart-contract product with owner-adjustable parameters. Validator rewards are a network/operator mechanism. A rate shown for one is not the rate for another. Avoid fixed APY, validator-count, reward-budget, or USD examples. These values change and must be read from the relevant live source. # Liquid Staking Rewards How Onyx Mainnet liquid staking rewards are represented. Users stake native XCN into `StakedXCNDirect` and receive stXCN position accounting. Rewards accrue according to the contract's current index and parameters. Reward rates, protocol fees, pause state, and contract parameters are variable and owner-adjustable. Published APR is an estimate, not a guarantee. For live staking data APIs, contract addresses, and integration requirements, see the [Exchange Integration Guide](/developer-guide/exchange-integration#liquid-staking-data-integration). For the user-facing staking flow and risks, see [Staking and stXCN](/onyx-defi/onyx-app/staking). # Validator Rewards High-level description of rewards for Onyx node operators. Validator or node rewards compensate eligible node operators under the network's current reward configuration. They are separate from stXCN liquid staking and from any account-staking mechanism. Eligibility, reward calculations, payment timing, and validator participation can change through network governance and operational policy. Use the [Validator Dashboard](https://validators.onyx.org) for current public status and the onboarding process for operator-specific terms. This page intentionally does not publish a fixed validator count, reward budget, APY, or hardware promise. # Running a Validator Current public boundary for joining Onyx Mainnet as a validator. Onyx is not currently onboarding new validators. The validator program is paused, and the Onyx team will let the community know when applications reopen. Watch the official [Onyx community](https://t.me/Onyx) for announcements. Do not deploy from old Testnet runbooks or copy a public validator address book into production. Existing operators must follow their private operational runbooks. User-facing documentation does not publish validator hostnames, IP addresses, keys, firewall rules, or restart procedures. # Validator Dashboard Public Onyx validator status dashboard. Use [validators.onyx.org](https://validators.onyx.org) for the current public view of validator status and network participation. Dashboard data is observational and may lag the consensus network. A stale or unavailable panel is not by itself proof that consensus has stopped, and a green panel is not a service-level guarantee. Integrations should also monitor the RPC block height and their own transaction receipts. # Overview Onyx Governance is controlled by the Onyx DAO through decentralized smart contracts and voted by XCN Stakers.
The Onyx Protocol operates under a decentralized governance framework, enabling XCN token holders to participate in protocol decision-making and upgrades. Governance is facilitated through four core smart contract components. The Onyx Governance module is available on [Onyx dApp.](https://app.onyx.org/#/governance) This module is exclusively controlled by XCN stakers on Ethereum. This section of the documentation hub goes over the entire Governance functions. {% hint style="info" %} Please note: XCN on other networks cannot control Onyx Governance at this time. {% endhint %} {% hint style="success" %} **Governance is expanding to Onyx Chain.** A native, stake-to-vote governance system for stXCN stakers is live on Onyx Chain itself, with proposals catalogued as Onyx Improvement Proposals (OIPs). It is a separate domain from the Ethereum governance described on this page — see [Governance on Onyx Chain](/governance/onyx-chain) for how it works. {% endhint %} ### Core Components * **XCN Token** – The governance token used for voting power and protocol participation. * **Staking Module** – A mechanism that allows users to stake XCN, granting them voting weight proportional to their staked balance. * **Governance Module (Governor)** – The primary contract responsible for processing governance proposals and vote execution. * **Timelock Contract** – A security mechanism ensuring that approved proposals are subject to a mandatory delay before execution, allowing the community to react if necessary. Together, these components enable a decentralized governance model where protocol modifications, parameter adjustments, and new asset integrations can be proposed, voted on, and executed through administrative functions within oToken contracts or the Comptroller contract. ### Governance Process **Proposal Eligibility**: To submit a governance proposal, an address must hold a minimum of 100,000,000 XCN in voting weight. Proposals consist of executable smart contract code, defining precise changes to the protocol, such as modifying interest rate models, listing new collateral assets, or adjusting risk parameters.
**Voting and Approval**: Once a proposal is submitted, a three-day (3-day) voting period is initiated. During this window, XCN holders can vote either for or against the proposal. A proposal is deemed successful if it receives: * A majority vote in favor. * A minimum of 200,000,000 XCN votes supporting it.\ Upon approval, the proposal is queued in the Timelock contract and becomes executable after a mandatory two-day (2-day) delay. This delay period allows the community to review the proposed changes before they are enacted on-chain. ## Staking XCN for Governance Participation
To obtain voting rights, users must stake XCN tokens. The amount of XCN staked determines the voting weight of an address. Governance power is dynamically adjusted based on staking activity: * Increasing stake grants additional voting weight. * Withdrawing XCN from staking automatically reduces voting power. This staking mechanism ensures that governance influence is directly proportional to active participation in securing and supporting the protocol. This governance structure ensures that protocol decisions remain community-driven and subject to transparent, on-chain governance mechanisms. ### Guardian The Guardian Wallet within Onyx Governance serves as a critical safeguard against malicious proposals, ensuring that even if a proposal achieves the necessary vote weight through hostile or manipulative means, it can be canceled before execution. This wallet is controlled by a trusted security council or smart contract logic designed to detect governance attacks, preventing unauthorized or harmful protocol changes. The Guardian has the authority to nullify proposals that violate security policies, such as those attempting to transfer funds improperly, alter fundamental contract logic, or introduce vulnerabilities into the system. By integrating this failsafe mechanism, Onyx Governance maintains a robust security posture while still enabling decentralized decision-making. The Guardian Wallet operates by continuously monitoring governance proposals and tracking vote behavior to identify anomalies, including vote concentration from potentially compromised accounts. If a proposal is flagged as malicious or harmful, the Guardian can intervene before the proposal progresses to execution within the Timelock contract. This feature ensures that the governance process remains resilient against coordinated attacks or governance takeovers. Additionally, the Guardian Wallet can be enhanced through onchain automation, further reducing the risk of unilateral actions while maintaining the integrity and trustworthiness of the Onyx Protocol's decentralized governance framework. # Governance on Onyx Chain How native on-chain governance works on Onyx Chain — stake-to-vote with stXCN, Onyx Improvement Proposals (OIPs), and Timelock-protected execution. Onyx Chain has its own native, fully on-chain governance system. Holders who stake XCN receive **stXCN**, and that staked position is what gives them the power to create proposals and vote on them directly on Onyx Chain (chain ID 327). Approved proposals are executed on-chain by a Timelock contract — no multisig or manual admin action is involved in carrying out an approved decision. Proposals on Onyx Chain are catalogued as **Onyx Improvement Proposals (OIPs)**: OIP-1, OIP-2, and so on. An OIP number is a permanent identifier assigned when the proposal is created on-chain. {% hint style="info" %} **Two governance domains.** Onyx governance exists on two chains, and they are deliberately separate: * **Ethereum governance** — the original Onyx Governor on Ethereum, controlled by XCN stakers on Ethereum. See the [Governance Overview](/governance/quickstart). * **Onyx Chain governance** — the native system described in this section, controlled by stXCN stakers on Onyx Chain. A proposal lives entirely on one chain. There is no cross-chain proposal, and XCN staked on one chain never counts as voting power on the other. {% endhint %} ## Stake-to-vote The single most important rule of Onyx Chain governance: > **Only staked XCN votes.** Voting power comes exclusively from stXCN — unstaked ("liquid") XCN held in a wallet on Onyx Chain has **zero** voting power. To participate, you first stake XCN through the [Onyx App](https://app.onyx.org) and receive stXCN. Your voting weight equals your stXCN balance — including accrued staking rewards — measured at a **snapshot block**. See [Voting Power and Snapshots](/governance/onyx-chain/voting-power) for exactly how and when your weight is measured. ## How a proposal flows ```mermaid graph LR A["Stake XCN
receive stXCN"] --> B["Snapshot
voting power recorded"] B --> C["Propose
OIP created on-chain"] C --> D["Vote
For / Against / Abstain"] D --> E["Timelock
2-day safety delay"] E --> F["Execute
change goes live"] ``` 1. **Stake** — XCN holders stake and hold stXCN. 2. **Snapshot** — voting power for the proposal is fixed at a published, verifiable snapshot block. 3. **Propose** — a staker whose snapshot weight meets the proposal threshold creates the OIP on-chain, including the exact actions to execute. 4. **Vote** — after a 1-day delay, voting opens for 2 days. Voters cast For, Against, or Abstain. 5. **Timelock** — an approved proposal is queued into the Timelock for a mandatory 2-day delay, giving the community time to review before anything changes. 6. **Execute** — after the delay, anyone can trigger execution. The Timelock performs the proposal's actions exactly as they were voted on. The full journey from proposal creation to execution takes a **minimum of about 5 days** (1-day voting delay + 2-day voting period + 2-day timelock delay). Every stage is covered step by step in the [Proposal Lifecycle](/governance/onyx-chain/proposal-lifecycle). ## Key parameters | Parameter | Value | | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | Voting asset | stXCN (staked XCN) only | | Proposal threshold | max(100,000,000 XCN, 0.10% of eligible staked supply), capped at 1,000,000,000 — currently **100,000,000** staked XCN of snapshot weight | | Voting delay | **1 day** after proposal creation | | Voting period | **2 days** | | Vote options | For / Against / Abstain | | Quorum | max(200,000,000 XCN, 2.00% of eligible staked supply), capped at 1,000,000,000 — currently **200,000,000**; **only For votes count toward quorum** | | Pass condition | For votes ≥ quorum **and** For > Against | | Timelock delay | **2 days** before execution | | Snapshot challenge window | **1 day** before a snapshot becomes usable | These parameters mirror the thresholds long used by Onyx governance on Ethereum (100M proposal threshold, 200M quorum), so voters moving between the two domains see familiar rules. ## What you can do as a... | Role | You need | You can | | ------------ | --------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | **Voter** | Any amount of stXCN at the snapshot | Vote For / Against / Abstain on any active OIP | | **Proposer** | ≥ proposal threshold in stXCN snapshot weight | Create an OIP with concrete on-chain actions | | **Observer** | Nothing | Watch every proposal, vote tally, queue, and execution live on the [explorer](https://explorer.onyx.org) | {% hint style="warning" %} **Rollout status.** Onyx Chain governance is activating in stages. The contracts described in this section are deployed on Onyx Mainnet, and proposal creation and voting open in the [Onyx App](https://app.onyx.org) once the first eligibility snapshot is finalized. Until activation completes, active governance voting continues through [Ethereum governance](/governance/quickstart). {% endhint %} ## In this section * [Proposal Lifecycle](/governance/onyx-chain/proposal-lifecycle) — every stage of an OIP, from draft to execution, and what a voter does at each one. * [Voting Power and Snapshots](/governance/onyx-chain/voting-power) — how stXCN becomes voting weight, how snapshots are published and verified, and the rules to keep your vote eligible. * [Governance Contracts](/governance/onyx-chain/contracts) — the Governor, Timelock, Snapshot Registry, and Grant Treasury contracts, with addresses and architecture diagrams. # Proposal Lifecycle Every stage of an Onyx Improvement Proposal (OIP) on Onyx Chain — creation, voting, quorum rules, the Timelock delay, and execution. Every proposal on Onyx Chain — every **OIP** — moves through the same on-chain state machine. This page walks through each stage, the exact timing, and what it means for you as a voter. ## The state machine ```mermaid graph TD P["Pending
voting delay — 1 day"] --> A["Active
voting open — 2 days"] A --> S["Succeeded
quorum reached, For above Against"] A --> D["Defeated
quorum missed or majority failed"] S --> Q["Queued
timelock delay — 2 days"] Q --> E["Executed
actions performed on-chain"] P --> C["Canceled"] A --> C Q --> C ``` | State | Meaning | Duration | | ------------- | -------------------------------------------------------------------------------------------------------- | ----------------------- | | **Pending** | The proposal exists on-chain but voting has not opened yet. | 1 day (voting delay) | | **Active** | Voting is open. Eligible stakers cast For, Against, or Abstain. | 2 days (voting period) | | **Succeeded** | Voting closed; the proposal passed. | Until queued | | **Defeated** | Voting closed; the proposal failed. Terminal state. | — | | **Queued** | The proposal's actions are locked into the Timelock and wait out the safety delay. | 2 days (timelock delay) | | **Executed** | The Timelock has performed the proposal's actions. Terminal state. | — | | **Canceled** | The proposal was withdrawn or blocked by the guardian safety mechanism before execution. Terminal state. | — | ## Stage by stage ### 1. Drafting and the proposal snapshot Before a proposal can be created, its voting snapshot is prepared: the eligible stXCN voting weight of every staker is measured at a specific finalized block, published on-chain to the [Snapshot Registry](/governance/onyx-chain/contracts#stxcn-snapshot-registry), and held open to public challenge for **1 day** before it is finalized. This finalized snapshot fixes *who can vote on this proposal and with how much weight* — nothing that happens to balances afterwards changes it. A proposal contains the **exact on-chain actions** it will perform — the target contracts, values, and encoded calls — plus a human-readable description. What you vote on is precisely what gets executed; there is no "interpretation" step between an approved vote and execution. ### 2. Creation (proposing) The proposer submits the proposal on-chain, attaching a cryptographic proof of their own snapshot weight. The Governor contract checks the proof against the latest finalized eligibility snapshot and requires: > **Proposal threshold:** the proposer's snapshot weight must be at least `max(100,000,000, 0.10% of eligible staked supply)` — currently **100,000,000** staked XCN. This threshold prevents spam while keeping proposing open to any sufficiently committed staker — no whitelist, no committee approval. Once the transaction confirms, the proposal has a permanent on-chain ID, is assigned its **OIP number**, and enters **Pending**. ### 3. Voting delay (1 day) For one day after creation, the proposal is visible but voting is closed. This window gives every voter time to: * read the proposal description and inspect the raw actions on the [explorer](https://explorer.onyx.org), * discuss it with the community, * decide how to vote. Your voting weight is already fixed at the snapshot — buying or staking during the delay does **not** add voting power for this proposal. ### 4. Voting period (2 days) Voting opens for two days. Every eligible staker casts one of three options: | Option | Effect | | ----------- | -------------------------------------------------------------------------------------- | | **For** | Supports the proposal. Counts toward quorum **and** the majority. | | **Against** | Opposes the proposal. Counts toward the majority only. | | **Abstain** | Participates without taking a side. Counts toward **neither** quorum nor the majority. | Votes are weighted by snapshot stXCN balance and each address can vote once per proposal. When you vote through the Onyx App, the app automatically attaches the cryptographic proof of your snapshot weight — you just choose For, Against, or Abstain and sign. ### 5. Tallying — how a proposal passes When the voting period ends, the proposal **succeeds** only if **both** conditions hold: 1. **Quorum (For-only):** For votes alone total at least `max(200,000,000, 2.00% of eligible staked supply)` — currently **200,000,000** XCN of staked weight. Against and Abstain votes never count toward quorum. 2. **Majority:** For votes strictly exceed Against votes. {% hint style="info" %} **Why For-only quorum matters:** a proposal cannot reach quorum through opposition or abstention. A heavily contested proposal with 190M For and 500M Against fails quorum *and* the majority — it needs genuine, affirmative support to pass. {% endhint %} If either condition fails, the proposal is **Defeated** — a terminal state. A defeated proposal can only be tried again as a brand-new proposal with a new vote. ### 6. Queue and Timelock (2 days) A succeeded proposal does not execute immediately. It is first **queued** into the [Timelock](/governance/onyx-chain/contracts#onyx-chain-timelock), which enforces a mandatory **2-day delay** before the actions can run. This delay is the community's final safety net: * everyone can review exactly what is about to execute, * integrators and users can prepare for the change, * if the proposal turns out to be malicious or defective, the **guardian** — an emergency safety role — can cancel it before execution. ### 7. Execution After the timelock delay expires, **anyone** can trigger execution. The Timelock performs the proposal's actions exactly as approved — for example, transferring a grant from the [Grant Treasury](/governance/onyx-chain/contracts#grant-treasury), or updating a protocol parameter. The result is permanently recorded on-chain and the proposal reaches **Executed**. ## Timeline at a glance ```mermaid graph LR T0["Day 0
Proposal created"] --> T1["Day 1
Voting opens"] T1 --> T3["Day 3
Voting closes"] T3 --> T3q["Day 3
Queued in Timelock"] T3q --> T5["Day 5
Earliest execution"] ``` From creation to execution is a **minimum of about 5 days**: 1-day voting delay + 2-day voting period + 2-day timelock delay (plus the 1-day snapshot challenge window that runs before creation). ## Voter checklist * ✅ **Stake early.** Only stXCN held at the snapshot counts — stake before a proposal you care about reaches its snapshot. See [Voting Power and Snapshots](/governance/onyx-chain/voting-power). * ✅ **Use the voting delay.** Read the description *and* glance at the raw actions — the actions are what actually executes. * ✅ **Vote within the 2-day window.** There are no late votes and no vote changes after the period closes. * ✅ **Abstain is not "quiet support."** Abstain never helps a proposal reach quorum. * ✅ **Watch the queue.** The 2-day timelock is your last chance to react to an approved change before it goes live. # Voting Power and Snapshots How stXCN becomes voting weight on Onyx Chain — snapshots, Merkle roots, the challenge window, and the rules that keep your vote eligible. Onyx Chain governance is **stake-to-vote**: your voting power is your staked XCN, measured at a published, verifiable snapshot. This page explains how that measurement works and what you need to do — and avoid — to make sure your stake counts. ## Where voting power comes from | Asset | Voting power on Onyx Chain | | ----------------------------- | ---------------------------------------------------------------------------------------------------- | | **stXCN** (staked XCN) | ✅ Full weight — your rebased stXCN balance at the snapshot block, including accrued staking rewards | | Native XCN in a wallet | ❌ Zero | | WXCN, LP tokens, other tokens | ❌ Zero | | XCN or stXCN on Ethereum | ❌ Zero on Onyx Chain (it votes in the separate [Ethereum governance](/governance/quickstart) domain) | You stake XCN and receive stXCN through the [Onyx App](https://app.onyx.org) — see [Staking and stXCN](/onyx-defi/onyx-app/staking). Because stXCN is a rebasing token whose balance grows with staking rewards, your voting weight automatically grows with your rewards too: **1 stXCN of balance at the snapshot = 1 unit of voting weight**. {% hint style="info" %} **Why stake-to-vote?** Requiring stake aligns voting power with long-term commitment to the network, and it gives governance one clean, on-chain source of truth for who holds what — the staking contract itself. {% endhint %} ## How a snapshot is made Voting power is not read live at vote time — it is fixed in advance by a **snapshot** with a public, verifiable pipeline: ```mermaid sequenceDiagram participant S as stXCN contract participant I as Snapshot builder participant R as Snapshot Registry (on-chain) participant C as Independent challenger participant G as Governor I->>S: Read every staker balance at snapshot block B I->>I: Build Merkle tree of (address, weight) leaves I->>R: Publish Merkle root + metadata on-chain C->>R: Recompute independently, 1-day challenge window Note over R: No valid challenge → root is finalized G->>R: Verify each vote against the finalized root ``` 1. **Measurement.** At a specific finalized block, the snapshot builder reads the exact stXCN balance of every staker directly from the staking contract's on-chain state. 2. **Merkle tree.** Every `(address, weight)` pair becomes a leaf in a Merkle tree. The single 32-byte root commits to the entire electorate — no balance can be added, removed, or altered without changing the root. 3. **On-chain publication.** The root is posted to the **Snapshot Registry** contract, together with metadata that pins the snapshot block, the total eligible supply, and the policy version it was built under. 4. **Challenge window (1 day).** An **independent challenger** — operating on separate infrastructure from the publisher — recomputes the snapshot from scratch. If its result differs, it challenges the root on-chain and the root is replaced, never silently corrected. A **guardian** role can additionally veto a bad root as an emergency backstop. 5. **Finalization.** Only after surviving the challenge window unchallenged does the root become **finalized** — and only finalized roots can ever be used for proposing or voting. The Governor rejects anything else. This design means you never have to trust the snapshot publisher: every root is independently re-verifiable by anyone from public on-chain data, and it is contested *before* it can affect any vote. ## Two kinds of snapshots | Snapshot | Purpose | When it is taken | | ------------------------ | ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | | **Eligibility snapshot** | Gates *proposal creation* — the proposer must prove threshold weight against the latest finalized eligibility snapshot. | Rolling — refreshed on a regular cadence | | **Proposal snapshot** | Fixes *voting weight and quorum* for one specific proposal. Bound permanently to that proposal at creation. | Once per proposal, shortly before it is created | Both kinds go through the same publish → challenge → finalize pipeline. ## Voting with proofs When you vote, the Governor verifies your claimed weight with a **Merkle proof** against the proposal's finalized snapshot root. In practice this is invisible: the Onyx App fetches your proof from the governance API and attaches it to your vote transaction automatically. You simply choose For, Against, or Abstain and sign. A vote without a valid proof counts as **zero weight** — the system fails closed. No proof, no unfinalized snapshot, and no mismatched snapshot can ever mint voting power. ## Practical rules for voters * **Stake before the snapshot.** If you stake after a proposal's snapshot block, you have zero weight *on that proposal* — but you will be included in future snapshots. * **Your weight is frozen per proposal.** Unstaking or transferring stXCN after the snapshot does not change your weight on proposals that already snapshotted you. It does remove you from *future* snapshots. * **No delegation (currently).** Voting weight belongs to the address that holds stXCN at the snapshot; there is no separate delegation registry. * **Rewards count.** Because stXCN rebases, the weight recorded at the snapshot already includes all staking rewards accrued up to that block. * **Check your power before voting.** The Onyx App displays your voting weight for each proposal once its snapshot is finalized. # Governance Contracts The smart contracts behind Onyx Chain governance — Governor, Timelock, Snapshot Registry, stXCN, and the Grant Treasury — with addresses and roles. Onyx Chain governance is implemented by a small set of purpose-built smart contracts deployed on Onyx Mainnet (chain ID 327). Each contract has one job, and no single party — including the team — can bypass the chain of checks they enforce together. ## Architecture ```mermaid graph TD subgraph "Proposal plane" U["Staker / Voter
(Onyx App or direct call)"] -->|"propose / vote
with Merkle proof"| GOV["Governor
OnyxGovernorV2"] GOV -->|"queue approved
proposal"| TL["Timelock
OnyxTimelockV2"] TL -->|"execute after
2 days"| TR["Grant Treasury
and other governed contracts"] end subgraph "Snapshot plane" ST["stXCN
StakedXCNDirect"] -.->|"balances read at
snapshot block"| REG["Snapshot Registry
StXCNSnapshotRegistryV2"] PUB["Snapshot publisher"] -->|"post root"| REG CHA["Independent challenger"] -->|"challenge bad roots
1-day window"| REG end GOV -->|"verify proofs"| REG GRD["Guardian"] -->|"veto bad root"| REG GRD -->|"cancel malicious
queued proposal"| TL ``` The flow of authority is one-directional: stakers' balances feed snapshots, snapshots authorize proposals and votes in the Governor, the Governor commands the Timelock, and only the Timelock touches governed contracts. ## Contract addresses (Onyx Mainnet, chain ID 327) | Contract | Address | | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | Governor (`OnyxGovernorV2`) | [`0xd6fA6779224deD996D8a7d04ba51Dc4769b08280`](https://explorer.onyx.org/address/0xd6fA6779224deD996D8a7d04ba51Dc4769b08280) | | Timelock (`OnyxTimelockV2`) | [`0xFC6a91f52dF6e3a8E0bB547de4265D71BD3feCA4`](https://explorer.onyx.org/address/0xFC6a91f52dF6e3a8E0bB547de4265D71BD3feCA4) | | Snapshot Registry (`StXCNSnapshotRegistryV2`) | [`0xB14461828f3b55edf1B82020724dF7560117dB88`](https://explorer.onyx.org/address/0xB14461828f3b55edf1B82020724dF7560117dB88) | | stXCN (`StakedXCNDirect`) | [`0xA553a603e2f84fEa6c1fc225E0945FE176C72F74`](https://explorer.onyx.org/address/0xA553a603e2f84fEa6c1fc225E0945FE176C72F74) | | Grant Treasury | [`0xB592E16d6A7EF093Aa77843E1cB7BB287584f17a`](https://explorer.onyx.org/address/0xB592E16d6A7EF093Aa77843E1cB7BB287584f17a) | | Wrapped XCN (WXCN, Treasury grant asset) | [`0x1a0Da75ADf091a69E7285e596bB27218D77E17a9`](https://explorer.onyx.org/address/0x1a0Da75ADf091a69E7285e596bB27218D77E17a9) | ## The contracts ### Governor The **Governor** (`OnyxGovernorV2`) is the heart of the system — it is where proposals are created, voted on, and driven through their [lifecycle](/governance/onyx-chain/proposal-lifecycle). It is built on the industry-standard OpenZeppelin Governor framework, extended with proof-based eligibility: * **Proof-bound proposing.** `proposeWithProof` requires the proposer to attach a Merkle proof of their snapshot weight; the Governor checks it against the latest finalized eligibility snapshot in the Registry and enforces the proposal threshold (currently 100,000,000 staked XCN). * **Proof-bound voting.** The only accepted vote path carries the voter's weight and Merkle proof; the Governor verifies every vote against the proposal's finalized snapshot root. A vote without a valid proof counts as zero. * **For-only quorum.** Quorum (currently 200,000,000) is satisfied by For votes alone; passage additionally requires For > Against. * **Fixed timing.** Voting delay (1 day) and voting period (2 days) are compiled into the contract — they cannot be quietly changed by an operator. The threshold and quorum *rates* can be adjusted only within hard-coded bounds, and only by governance itself. ### Onyx Chain Timelock The **Timelock** (`OnyxTimelockV2`) is the executor and the safety buffer. When a proposal succeeds, the Governor queues its actions here, where they must wait a mandatory **2 days** before execution: * The Timelock — not the Governor, not any admin — is the **owner of governed contracts**. A governed contract only changes when the Timelock executes an approved proposal. * The Governor is the only address allowed to queue operations (proposer role). * The guardian holds a **cancel** right on the Timelock, so a malicious proposal that slipped through a vote can still be stopped during the 2-day delay — but the guardian can never *create* or *fast-track* anything. ### stXCN Snapshot Registry The **Snapshot Registry** (`StXCNSnapshotRegistryV2`) is the on-chain home of [voting-power snapshots](/governance/onyx-chain/voting-power). It stores each published Merkle root with its full metadata (snapshot block, eligible supply, policy version) and enforces the root lifecycle: * **Post → challenge (1 day) → finalize.** Only roots that survive the challenge window become usable for governance. * **Strict role separation.** The publisher, challenger, and guardian are required to be distinct parties — the contract itself rejects a configuration where one address holds two of these roles. * **Fail-closed verification.** The Governor's proof checks revert on an unfinalized root, a wrong-purpose root, a mismatched policy, or a paused registry. There is no fallback path that skips verification. ### stXCN (StakedXCNDirect) **stXCN** is the liquid staking token you receive for staking XCN — and the sole source of voting power on Onyx Chain. It is a rebasing token: your balance grows as staking rewards accrue, and governance snapshots measure that grown balance. stXCN itself is documented in [Staking and stXCN](/onyx-defi/onyx-app/staking). ### Grant Treasury The **Grant Treasury** is the first contract governed end-to-end by Onyx Chain governance. It holds WXCN and exposes exactly one privileged function — paying out a grant to a recipient — callable **only by its owner, the Timelock**. In other words: > The only way funds leave the Grant Treasury is a full OIP: proposal → vote → quorum → 2-day timelock → execution. This makes community grant funding a pure governance decision, with every step publicly visible and verifiable on the [explorer](https://explorer.onyx.org). ## Operational roles | Role | What it can do | What it cannot do | | ----------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------ | | **Publisher** | Post new snapshot roots to the Registry | Finalize its own root early, vote, or execute anything | | **Challenger** | Dispute an incorrect root during the 1-day window | Post roots or interfere with correct ones | | **Guardian** | Veto a bad root; cancel a malicious proposal during the timelock delay | Create, fast-track, or execute proposals; move funds | | **Governor (contract)** | Queue approved proposals into the Timelock | Execute anything without the 2-day delay | | **Timelock (contract)** | Execute approved proposals after the delay | Act without an approved, queued proposal | {% hint style="info" %} **Verify, don't trust.** All the contracts above are deployed on Onyx Mainnet and every proposal, snapshot root, vote, queue, and execution is a public transaction. You can independently verify any governance action on the [explorer](https://explorer.onyx.org) using the addresses in the table above. {% endhint %} # Security Governance Security and Stability Mechanisms The Onyx Governor follows a structured governance model that balances decentralization with security and efficiency. The **Timelock** contract prevents sudden, unauthorized modifications to the protocol, ensuring all decisions undergo rigorous scrutiny before being enacted. Additionally, the on-chain governance mechanism provides an immutable and transparent record of all proposals, votes, and implementations, reinforcing accountability and trust within the community. By leveraging Ethereum-based smart contract governance, the Onyx Governor facilitates an efficient and transparent decision-making process that aligns with the interests of long-term stakeholders, ultimately promoting protocol sustainability and robust security standards.
# Onyx Points The Onyx App includes a Points experience. Eligibility, seasons, supported assets, multipliers, and claim rules are program state and can change. Use the live [Onyx App](https://app.onyx.org) as the source for current participation rules. Never send assets or approve contracts based only on a historical points page. Currently we are on **Season 3** of the Onyx Points Program with 5 million daily points awarded. # Earning Points Point-earning actions are defined by the active Onyx Points program. Confirm the current season, eligible asset, application, chain, and wallet action in the Onyx App before participating. Historical categories do not guarantee current eligibility. # Whitelisted Assets The active Points whitelist is mutable. Consult the Onyx App for the current list and verify every token address in the relevant explorer. The [historic whitelist](https://github.com/Onyx-Protocol/goliath-docs/tree/fix/onyx-user-facing-brand/points/whitelisted-assets/historic-whitelist.md) is retained only as historical context and must not be used as a current allowlist. The current Whitelisted Assets are as follow and only on the Onyx blockchain (Chain ID 327):
AssetWeightContract
Staked XCN (stXCN)50%0xA553a603e2f84fEa6c1fc225E0945FE176C72F74
USDC (USDC)25%0xC8410270bb53f6c99A2EFe6eD3686a8630Efe22B
Ether (ETH)25%0x9253587505c3B7E7b9DEE118AE1AcB53eEC0E4b6
# AI Agent Summary of the Onyx AI Agent deployed for users of XCN Ledger. ## Onyx AI: Autonomous Blockchain Intelligence on the XCN Ledger Onyx AI is a next-generation, blockchain-native autonomous agent engineered to interface directly with decentralized infrastructure on the XCN Ledger. It combines on-chain execution capabilities with off-chain artificial intelligence reasoning, enabling intelligent automation of complex tasks across decentralized finance (DeFi), token management, and cross-chain operations. This hybrid agent is designed to operate with programmable autonomy, execute smart contract interactions, and respond to user prompts with contextual awareness and transaction precision. At its core, Onyx AI functions as a self-directed, modular smart agent deployed natively on the XCN Ledger, leveraging XCN as the network fee asset for computation, execution, and value transfer. XCN is required to purchase `Credits` that enable the user to utilize prompts with the Agent. The agent is architected to bridge the gap between AI-driven logic systems and the deterministic nature of EVM-compatible smart contract environments. It operates under a permissionless framework but utilizes embedded security policies to ensure safe execution across trusted protocols and wallet environments. Where the product presents a gasless experience, network fees are sponsored or abstracted from the user rather than removed from the underlying blockchain transaction. Onyx AI marks a pivotal shift in the evolution of decentralized automation. By tightly integrating artificial intelligence with blockchain-native execution, it enables a future where agents—not just humans—can reason, transact, and operate autonomously within secure, deterministic environments. With Onyx AI, intelligent on-chain automation becomes accessible, programmable, and trustless. # Core Features Onyx AI Core Blockchain Features ## Core Capabilities of Onyx AI Onyx AI supports a wide spectrum of on-chain interactions, with dynamic routing logic that enables it to choose optimal execution paths based on real-time conditions.\ \ **Key supported features include:**
**✅ Token Minting** * Interacts with ERC-20/ERC-721/ERC-1155 minting contracts. * Can deploy new tokens or mint additional supply of existing contracts. * AI-driven contract parsing ensures safe execution against verified or audited contract schemas. * Optional metadata integration via IPFS or Arweave for NFT mints.
**✅ Token Swaps** * Executes token swaps across integrated DEXs and aggregators using optimal slippage and gas strategies. * Supports multi-hop routing for maximizing token output via liquidity pathfinding. * Swap strategies are dynamically computed based on market volatility, historical spreads, and protocol fees.
**✅ Token Transfers** * Sends ERC-20 and native assets (XCN) to user-defined or AI-determined addresses. * Transaction batching supported for efficient multi-address disbursements. * AI-enhanced memo tagging to provide context-aware labeling (e.g., payroll, yield allocation).
**✅ Real-Time Cryptocurrency Market Data Retrieval** * Integrates with oracle networks and off-chain APIs to retrieve up-to-date pricing, market cap, volume, and volatility data. * Context-aware decision-making (e.g., “Should I swap USDC for ETH now?”) supported through dynamic prompt analysis. * Supports watchlist creation and condition-based alerts for AI-executed trading triggers.
**✅ NFT Metadata & Floor Price Access** * Queries NFT contract metadata, image files, ownership records, rarity, and floor price from both on-chain events and off-chain indexers (e.g., The Graph, OpenSea APIs). * Can be used to trigger intelligent decisions like NFT liquidation, collection-based trading, or alerting based on price thresholds.
**✅ Cross-Chain Bridging** * Bridges supported tokens across EVM-compatible blockchains (e.g., Ethereum, Arbitrum, BNB Chain, Polygon). * AI selects optimal bridge routes considering gas cost, bridge delay, reliability, and security rating of the bridge protocol. * Uses standardized bridge interfaces such as LayerZero, Connext, or Stargate when available.
**✅ Wallet Balance Checks** * Retrieves real-time token and NFT balances across multi-chain wallet environments. * Can parse complex wallet states, including LP positions, staked assets, yield-bearing vault tokens, and delegated voting rights. * Generates human-readable summaries or AI-suggested actions (e.g., “You have idle stablecoins, consider supplying to lending protocols”). # Wallet Infrastructure Onyx AI Agent's Blockchain Wallet Infrastructure ## AI Agent Wallet Architecture Each instance of Onyx AI is provisioned with a dedicated on-chain wallet, referred to as an agent wallet. These wallets are permissionless and have no centralized control. These wallets serve as the execution layer for autonomous tasks. Users can: * Fund the agent wallet with any ERC20 token or Ethereum on Onyx, Ethereum, Base, and BNB Chain. * Predefine operational rules (e.g., budget limits, whitelisted dApps, risk thresholds). * Allow the agent to execute autonomously within those constraints, using AI to interpret prompts and derive task sequences. Wallets are deterministic, derived via cryptographic hashing of user identifiers and secured by permissionless layers that enforce non-custodial ownership. Additionally, agent wallets can integrate time locks, multisig guards, and circuit breakers to ensure execution safety. *** ### Deployment Environment and Ecosystem Integration * Blockchain: Onyx, Ethereum, Base, BNB * Gas Token: Onyx transactions incur network fees paid in XCN. Where the agent presents a gasless experience, the fee is sponsored or abstracted through `Credits`; the underlying network fee is not eliminated. See [Network Fees](/developer-guide/network-fees). * dApp Support: Onyx AI is extensible and continuously updated with support for top-tier dApps in categories including DeFi, NFT marketplaces, staking, and governance. *** *Example Architecture*
# EVM JSON-RPC Supported EVM JSON-RPC usage on Onyx Mainnet. Mainnet endpoint: `https://rpc.onyx.org` ## Common methods The public relay supports the EVM methods commonly needed by wallets, exchanges, and applications, including: * Network and blocks: `eth_chainId`, `net_version`, `eth_blockNumber`, `eth_getBlockByNumber`, `eth_getBlockByHash` * Accounts and state: `eth_getBalance`, `eth_getTransactionCount`, `eth_getCode`, `eth_getStorageAt` * Transactions: `eth_sendRawTransaction`, `eth_getTransactionByHash`, `eth_getTransactionReceipt` * Contracts and fees: `eth_call`, `eth_estimateGas`, `eth_gasPrice`, `eth_maxPriorityFeePerGas` * Events: `eth_getLogs` and supported filter/subscription methods Onyx does not promise support for every Ethereum client extension, debug method, pending-pool behavior, or future RPC method. Probe the exact method set your application requires and handle `method not found` or `method not supported` responses. ## Example ```bash curl -sS https://rpc.onyx.org \ -H 'content-type: application/json' \ --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' ``` ## Onyx-specific considerations * Native XCN is returned in 18-decimal RPC units but settles at 8-decimal ledger precision. * `eth_estimateGas` must be used for transfers because the recipient account may need to be created. * Read the current gas price; do not use fixed price tiers copied from another network. See [Network Fees](/developer-guide/network-fees) for Onyx's fee calculation and USD denomination. * Public capacity and throttling can change. Back off on transient errors and arrange dedicated service before depending on a specific SLA. # XCN Token XCN on Ethereum and as the native coin of Onyx Mainnet. XCN is the native coin of Onyx Mainnet and is used for gas and native transfers. ## Ethereum XCN ERC-20 contract: ``` 0xA2cd3D43c775978A96BdBf12d733D5A1ED94fb18 ``` [View Ethereum XCN on Etherscan](https://etherscan.io/address/0xA2cd3D43c775978A96BdBf12d733D5A1ED94fb18) ## Wrapped XCN on Onyx Wrapped XCN (WXCN) is the ERC-20 representation used by Onyx smart contracts and DEX pools: ``` 0x1a0Da75ADf091a69E7285e596bB27218D77E17a9 ``` [View WXCN on the Onyx Explorer](https://explorer.onyx.org/address/0x1a0Da75ADf091a69E7285e596bB27218D77E17a9) [The Onyx bridge](https://app.onyx.org/en/bridge) moves XCN between its Ethereum ERC-20 representation and native Onyx representation. Supply, staking, bridge reserves, and market values are mutable; use current explorer, Markets, and bridge data rather than a fixed snapshot in documentation. Native XCN uses 8-decimal ledger precision even though JSON-RPC represents values with 18-decimal scaling. See [XCN Decimal Handling](/developer-guide/decimal-handling). # Smart Contract Addresses Live-verified smart contract addresses for Onyx Mainnet and Ethereum counterparts. These addresses were rechecked against public RPC bytecode and relevant public APIs on 2026-07-14. Reverify before a production integration. Each address is shown as inline code for easy copying and links directly to its explorer page. | Contract | Address | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | Wrapped XCN (WXCN) | [`0x1a0Da75ADf091a69E7285e596bB27218D77E17a9`](https://explorer.onyx.org/address/0x1a0Da75ADf091a69E7285e596bB27218D77E17a9) | | Uniswap V2 Factory | [`0x008c99EedA17E193e5F788536234C6b3520B8D15`](https://explorer.onyx.org/address/0x008c99EedA17E193e5F788536234C6b3520B8D15) | | Uniswap V2 Router02 | [`0xa973c5626eEaF7F482439753953e9B28C6aF3674`](https://explorer.onyx.org/address/0xa973c5626eEaF7F482439753953e9B28C6aF3674) | | Bridged ETH | [`0x9253587505c3B7E7b9DEE118AE1AcB53eEC0E4b6`](https://explorer.onyx.org/address/0x9253587505c3B7E7b9DEE118AE1AcB53eEC0E4b6) | | Bridged USDC | [`0xC8410270bb53f6c99A2EFe6eD3686a8630Efe22B`](https://explorer.onyx.org/address/0xC8410270bb53f6c99A2EFe6eD3686a8630Efe22B) | | XCN/USDC LP | [`0x57541cC904E863d6CBEe5Dbe5F55aCA799BC0e9F`](https://explorer.onyx.org/address/0x57541cC904E863d6CBEe5Dbe5F55aCA799BC0e9F) | | ETH/USDC LP | [`0x6dc9C9E36a19a57A6cbe9E724a74bD4d98D2EE12`](https://explorer.onyx.org/address/0x6dc9C9E36a19a57A6cbe9E724a74bD4d98D2EE12) | | BridgeMint | [`0x1d14ae13ca030eb5e9e2857e911af515cf5ffff2`](https://explorer.onyx.org/address/0x1d14ae13ca030eb5e9e2857e911af515cf5ffff2) | | StakedXCNDirect (stXCN) | [`0xA553a603e2f84fEa6c1fc225E0945FE176C72F74`](https://explorer.onyx.org/address/0xA553a603e2f84fEa6c1fc225E0945FE176C72F74) | | Ethereum BridgeLock | [`0xa9fd64b5095d626f5a3a67e6db7fb766345f8092`](https://etherscan.io/address/0xa9fd64b5095d626f5a3a67e6db7fb766345f8092) | | Ethereum XCN | [`0xA2cd3D43c775978A96BdBf12d733D5A1ED94fb18`](https://etherscan.io/address/0xA2cd3D43c775978A96BdBf12d733D5A1ED94fb18) | | Ethereum USDC | [`0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48`](https://etherscan.io/address/0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48) | # FAQ and Troubleshooting Current Onyx limitations and troubleshooting guidance. ## Is Onyx a rollup or Layer 3? No. Onyx is an EVM-compatible Layer 1 with its own aBFT consensus. ## Why did a transfer to a new address run out of gas? The recipient account may need to be created on first receipt. Use `eth_estimateGas` with the real transaction and do not hardcode `21,000`. ## Why does native XCN have 18 RPC decimals but only 8 usable decimals? JSON-RPC uses an 18-decimal wei-style representation while the native ledger settles in `tinyxcn` at 8-decimal precision. Align native values to multiples of `10^10` RPC units. ## How much does an Onyx transaction cost? The fee depends on the gas used and the current gas price. Onyx prices network resources in USD terms and converts the charge into XCN using the network's current conversion rate. See [Network Fees](/developer-guide/network-fees) for the latest verified snapshot, examples, and live queries. ## Which RPC methods are supported? Common wallet, transaction, contract-call, log, and subscription methods are supported. Complete parity with every Ethereum client-specific extension is not promised. Test the methods your product requires. ## Why is the bridge unavailable or still processing? Check the app maintenance state and the operation status. Source confirmation, security holds, relayer state, and destination submission are distinct phases. Do not resubmit the same transfer merely because it has not completed within an assumed time. ## Where do I find current bridge fees and minimums? Use `https://app.onyx.org/api/bridge-proxy/api/v1/bridge/limits` and a live fee quote. Documentation examples are not a source of truth for mutable values. ## Where do I find current staking APR and TVL? Use the Onyx App or the live staking endpoint described in the [Exchange Integration Guide](/developer-guide/exchange-integration#liquid-staking-data-integration). Check timestamp and freshness fields before relying on the rate. Rates are variable and owner-adjustable. ## Why does Markets show an asset that I cannot trade or bridge? Metadata presence is not support. Check active execution markets, live bridge limits, and the [contract registry](/reference/contracts). Only enable assets that the current app and API explicitly support. ## Does the validator dashboard prove the whole network is healthy? No single UI proves consensus, indexing, and RPC health together. Compare dashboard status, current RPC block height, explorer/mirror freshness, and your own receipts. # Terms of Service Onyx DApp Terms of Service ## Terms of Service **Updated: March 1, 2023** The app.onyx.org website (the “Interface” or “App”) is an open-source and public website hosted on GitHub by Onyx DAO (“we”, “our”, or “us”). The Interface provides access to a decentralized protocol on the Ethereum blockchain that allows suppliers and borrowers of certain digital assets to participate in autonomous interest rate markets (the “Protocol”). This Terms of Service Agreement (the “Agreement”) explains the terms and conditions by which you may access and use the Interface. You must read this Agreement carefully. By accessing or using the Interface, you signify that you have read, understand, and agree to be bound by this Agreement in its entirety. If you do not agree, you are not authorized to access or use the Interface. **1. Modification of this Agreement** We reserve the right, in our sole discretion, to modify this Agreement from time to time. If we make any modifications, we will notify you by updating the date at the top of the Agreement and by maintaining a current version of the Agreement at[ https://docs.onyx.org/terms-of-service](https://docs.onyx.org/terms-of-service). All modifications will be effective when they are posted, and your continued use of the Interface will serve as confirmation of your acceptance of those modifications. If you do not agree with any modifications to this Agreement, you must immediately stop accessing and using the Interface. **2. Eligibility** To access or use the Interface, you must be able to form a legally binding contract with us. Accordingly, you represent that you are at least eighteen years old and have the full right, power, and authority to enter into and comply with the terms and conditions of this Agreement on behalf of yourself and any company or legal entity for which you may access or use the Interface. You further represent that you are not a citizen, resident, or member of any jurisdiction or group that is subject to economic sanctions by the United States or the United Kingdom, or where your use of the Interface would be illegal or otherwise violate any applicable law. You further represent that your access and use of the Interface will fully comply with all applicable laws and regulations, and that you will not access or use the Interface to conduct, promote, or otherwise facilitate any illegal activity. **3. Proprietary Rights** We own all intellectual property and other rights in the Interface and its contents, including (but not limited to) software, text, images, trademarks, service marks, copyrights, patents, and designs. Unless expressly authorized by us, you may not copy, modify, adapt, rent, license, sell, publish, distribute, or otherwise permit any third party to access or use the Interface or any of its contents. Provided that you are eligible, you are hereby granted a single, personal, limited license to access and use the Interface. This license is non-exclusive, non-transferable, and freely revocable by us at any time without notice or cause. Use of the Interface or its contents for any purpose not expressly permitted by this Agreement is strictly prohibited. Unlike the Interface, the Protocol is comprised entirely of open-source software running on the public Ethereum blockchain and is not our proprietary property. **4. Privacy** We care about your privacy. Although we will comply with all valid subpoena requests, we will carefully consider each request to ensure that it comports with the spirit and letter of the law, and we will not hesitate to challenge invalid, overbroad, or unconstitutional requests as appropriate. We use commercially reasonable safeguards to preserve the integrity and security of your personally identifiable information (“PII”) and aggregate data. However, we cannot guarantee that unauthorized third parties will never be able to obtain or use your PII or aggregate data for improper purposes. You acknowledge that you provide your PII and aggregate data at your own risk. By accessing and using the Interface, you understand and consent to our collection, use, and disclosure of your PII and aggregate data. **5. Prohibited Activity** You agree not to engage in, or attempt to engage in, any of the following categories of prohibited activity in relation to your access and use of the Interface: · Intellectual Property Infringement. Activity that infringes on or violates any copyright, trademark, service mark, patent, right of publicity, right of privacy, or other proprietary or intellectual property rights under the law. · Cyberattack. Activity that seeks to interfere with or compromise the integrity, security, or proper functioning of any computer, server, network, personal device, or other information technology system, including (but not limited to) the deployment of viruses and denial of service attacks. · Fraud and Misrepresentation. Activity that seeks to defraud us or any other person or entity, including (but not limited to) providing any false, inaccurate, or misleading information in order to unlawfully obtain the property of another. · Market Manipulation. Activity that violates any applicable law, rule, or regulation concerning the integrity of trading markets, including (but not limited to) the manipulative tactics commonly known as spoofing and wash trading. · Any Other Unlawful Conduct. Activity that violates any applicable law, rule, or regulation of the United States or another relevant jurisdiction, including (but not limited to) the restrictions and regulatory requirements imposed by U.S. law. **6. No Professional Advice** All information provided by the Interface is for informational purposes only and should not be construed as professional advice. You should not take, or refrain from taking, any action based on any information contained in the Interface. Before you make any financial, legal, or other decisions involving the Interface, you should seek independent professional advice from an individual who is licensed and qualified in the area for which such advice would be appropriate. **7. No Warranties** The Interface is provided on an “**AS IS**” and “**AS AVAILABLE**” basis. To the fullest extent permitted by law, we disclaim any representations and warranties of any kind, whether express, implied, or statutory, including (but not limited to) the warranties of merchantability and fitness for a particular purpose. You acknowledge and agree that your use of the Interface is at your own risk. We do not represent or warrant that access to the Interface will be continuous, uninterrupted, timely, or secure; that the information contained in the Interface will be accurate, reliable, complete, or current; or that the Interface will be free from errors, defects, viruses, or other harmful elements. No advice, information, or statement that we make should be treated as creating any warranty concerning the Interface. We do not endorse, guarantee, or assume responsibility for any advertisements, offers, or statements made by third parties concerning the Interface. **8. No Fiduciary Duties** This Agreement is not intended to, and does not, create or impose any fiduciary duties on us. To the fullest extent permitted by law, you acknowledge and agree that we owe no fiduciary duties or liabilities to you or any other party, and that to the extent any such duties or liabilities may exist at law or in equity, those duties and liabilities are hereby irrevocably disclaimed, waived, and eliminated. You further agree that the only duties and obligations that we owe you are those set out expressly in this Agreement. **9. Compliance Obligations** The Interface may not be available or appropriate for use in other jurisdictions. By accessing or using the Interface, you agree that you are solely and entirely responsible for compliance with all laws and regulations that may apply to you. You may not use the Interface if you are a citizen, resident, or member of any jurisdiction or group that is subject to economic sanctions by the United States of the United Kingdom, or if your use of the Interface would be illegal or otherwise violate any applicable law. The Interface and all of its contents are solely directed to individuals, companies, and other entities located within the United States or the United Kingdom. **10. Assumption of Risk** By accessing and using the Interface, you represent that you understand the inherent risks associated with using cryptographic and blockchain-based systems, and that you have a working knowledge of the usage and intricacies of digital assets such as bitcoin (BTC), ether (ETH), and other digital tokens such as those following the Ethereum Token Standard (ERC-20). You further understand that the markets for these digital assets are highly volatile due to factors including (but not limited to) adoption, speculation, technology, security, and regulation. You acknowledge that the cost and speed of transacting with cryptographic and blockchain-based systems such as Ethereum are variable and may increase dramatically at any time. You further acknowledge the risk that your digital assets may lose some or all of their value while they are supplied to the Protocol. If you borrow digital assets from the Protocol, you will have to supply digital assets of your own as collateral. If your collateral declines in value such that it is no longer sufficient to secure the amount that you borrowed, others may interact with the Protocol to seize your collateral in a liquidation event. You further acknowledge that we are not responsible for any of these variables or risks, do not own or control the Protocol, and cannot be held liable for any resulting losses that you experience while accessing or using the Interface. Accordingly, you understand and agree to assume full responsibility for all of the risks of accessing and using the Interface and interacting with the Protocol. **11. Third-Party Resources and Promotions** The Interface may contain references or links to third-party resources, including (but not limited to) information, materials, products, or services, that we do not own or control. In addition, third parties may offer promotions related to your access and use of the Interface. We do not endorse or assume any responsibility for any such resources or promotions. If you access any such resources or participate in any such promotions, you do so at your own risk, and you understand that this Agreement does not apply to your dealings or relationships with any third parties. You expressly relieve us of any and all liability arising from your use of any such resources or participation in any such promotions. **12. Release of Claims** You expressly agree that you assume all risks in connection with your access and use of the Interface and your interaction with the Protocol. You further expressly waive and release us from any and all liability, claims, causes of action, or damages arising from or in any way relating to your use of the Interface and your interaction with the Protocol. If you are a California resident, you waive the benefits and protections of California Civil Code § 1542, which provides: “\[a] general release does not extend to claims that the creditor or releasing party does not know or suspect to exist in his or her favor at the time of executing the release and that, if known by him or her, would have materially affected his or her settlement with the debtor or released party.” **13. Indemnity** You agree to hold harmless, release, defend, and indemnify us and our officers, directors, employees, contractors, agents, affiliates, and subsidiaries from and against all claims, damages, obligations, losses, liabilities, costs, and expenses arising from: (a) your access and use of the Interface; (b) your violation of any term or condition of this Agreement, the right of any third party, or any other applicable law, rule, or regulation; and (c) any other party’s access and use of the Interface with your assistance or using any device or account that you own or control. **14. Limitation of Liability** Under no circumstances shall we or any of our officers, directors, employees, contractors, agents, affiliates, or subsidiaries be liable to you for any indirect, punitive, incidental, special, consequential, or exemplary damages, including (but not limited to) damages for loss of profits, goodwill, use, data, or other intangible property, arising out of or relating to any access or use of the Interface, nor will we be responsible for any damage, loss, or injury resulting from hacking, tampering, or other unauthorized access or use of the Interface or the information contained within it. We assume no liability or responsibility for any: (a) errors, mistakes, or inaccuracies of content; (b) personal injury or property damage, of any nature whatsoever, resulting from any access or use of the Interface; (c) unauthorized access or use of any secure server or database in our control, or the use of any information or data stored therein; (d) interruption or cessation of function related to the Interface; (e) bugs, viruses, trojan horses, or the like that may be transmitted to or through the Interface; (f) errors or omissions in, or loss or damage incurred as a result of the use of, any content made available through the Interface; and (g) the defamatory, offensive, or illegal conduct of any third party. Under no circumstances shall we or any of our officers, directors, employees, contractors, agents, affiliates, or subsidiaries be liable to you for any claims, proceedings, liabilities, obligations, damages, losses, or costs in an amount exceeding the amount you paid to us in exchange for access to and use of the Interface, or $100.00, whichever is greater. This limitation of liability applies regardless of whether the alleged liability is based on contract, tort, negligence, strict liability, or any other basis, and even if we have been advised of the possibility of such liability. Some jurisdictions do not allow the exclusion of certain warranties or the limitation or exclusion of certain liabilities and damages. Accordingly, some of the disclaimers and limitations set forth in this Agreement may not apply to you. This limitation of liability shall apply to the fullest extent permitted by law. **15. Dispute Resolution** We will use our best efforts to resolve any potential disputes through informal, good faith negotiations. If a potential dispute arises, you must contact us by sending an email to so that we can attempt to resolve it without resorting to formal dispute resolution. If we aren’t able to reach an informal resolution within sixty days of your email, then you and we both agree to resolve the potential dispute according to the process set forth below. Any claim or controversy arising out of or relating to the Interface, this Agreement, or any other acts or omissions for which you may contend that we are liable, including (but not limited to) any claim or controversy as to arbitrability (“Dispute”), shall be finally and exclusively settled by arbitration under the LCIA Arbitration Procedures. You understand that you are required to resolve all Disputes by binding arbitration. The arbitration shall be held on a confidential basis before a single arbitrator, who shall be selected pursuant to LCIA rules. The arbitration will be held in London, United Kingdom, unless you and we both agree to hold it elsewhere. Unless we agree otherwise, the arbitrator may not consolidate your claims with those of any other party. Any judgment on the award rendered by the arbitrator may be entered in any court of competent jurisdiction. **16. Class Action and Jury Trial Waiver** You must bring any and all Disputes against us in your individual capacity and not as a plaintiff in or member of any purported class action, collective action, private attorney general action, or other representative proceeding. This provision applies to class arbitration. You and we both agree to waive the right to demand a trial by jury. **17. Governing Law** You agree that the laws of the London, United Kingdom without regard to principles of conflict of laws, including criminal or civil, that govern this Agreement and any Dispute between you and us. You further agree that the Interface shall be deemed to be based solely in London, United Kingdom, and that although the Interface may be available in other jurisdictions, its availability does not give rise to general or specific personal jurisdiction in any forum outside of London. Any arbitration conducted pursuant to this Agreement shall be governed by the LICA Arbitration procedures. You agree that London is the proper forum for any appeals of an arbitration award or for court proceedings in the event that this Agreement’s binding arbitration clause is found to be unenforceable. [
](https://docs.onyx.org/security/bug-bounty-program)
# Bug Bounty The Onyx Bug Bounty Program is designed for a community-centric problem-solving approach for the Onyx smart contracts. At Onyx, security is fundamental to our mission. We highly value the contributions of ethical hackers who help us uphold the highest standards of security across the Onyx ecosystem. While Onyx has undergone rigorous professional audits and formal verification, it operates on evolving technology that may still contain undiscovered vulnerabilities. We encourage the community to actively audit our smart contracts and infrastructure and responsibly disclose any security concerns. This program is designed to incentivize responsible security research, outlining the expectations for ethical vulnerability disclosure and the rewards available for eligible findings. ### Rewards Onyx offers substantial rewards for vulnerabilities that could lead to the loss or freezing of assets or otherwise cause harm to users. The reward amount is determined based on the severity and exploitability of the vulnerability. Eligible discoveries may receive rewards ranging from $500 to $150,000, in accordance with the terms outlined below. ### Scope **Primary Scope:** The primary focus of the bug bounty program is vulnerabilities impacting the on-hain Onyx Protocol, deployed on Ethereum Mainnet, specifically for the contract addresses listed in this developer documentation. This scope is subject to change as new contracts are deployed or existing contracts are deprecated. **Out-of-scope** items include: * Vulnerabilities in third-party contracts built on top of Onyx (e.g., smart contract wallets). * Issues that require admin key ownership. **Secondary Scope:** The program also includes vulnerabilities affecting the Onyx Interface hosted at app.onyx.org, particularly those that could lead to unauthorized account access or asset manipulation. **Out of Scope:** * Vulnerabilities affecting test environments (Rinkeby, other testnets, and staging servers), unless they also impact the Onyx Protocol or Interface in a way that could put user funds at risk. ### Disclosure Process All vulnerability disclosures should be submitted to with detailed steps for reproducing the issue. Reports may be submitted in written or video format to ensure clarity. Onyx will acknowledge all valid submissions promptly. #### **Eligibility** **Requirements** To qualify for a bounty reward, you must: * Identify a previously unreported, original, and non-public vulnerability within the defined scope. * Provide a detailed disclosure that enables Onyx engineers to reproduce and resolve the issue efficiently. * Be at least 18 years old. * Submit your report individually or with documented company approval (if submitting on behalf of an organization). * Not be subject to U.S. sanctions or reside in a U.S.-embargoed country. * Not be a current or former Onyx employee, vendor, contractor, or affiliate of a vendor or contractor. #### Rules of Engagement To encourage ethical security research and distinguish good-faith efforts from malicious activity, researchers must: * Follow program terms and any other applicable agreements. If conflicts arise, the bug bounty program terms take precedence. * Report vulnerabilities promptly. * Avoid causing harm, including privacy violations, service disruptions, or data loss. * Use only for all communications regarding vulnerabilities. * Maintain confidentiality regarding discovered vulnerabilities until they are patched. * Limit testing to in-scope systems and avoid interacting with accounts not explicitly authorized for testing. * Refrain from extortion, blackmail, or any unlawful activities. ### What You Can Expect from Onyx When engaging with Onyx under this program, we commit to: * Offering competitive rewards for eligible findings, with payouts determined based on severity and exploitability at Onyx's discretion. * Providing Safe Harbor for researchers who comply with program guidelines, ensuring Onyx will not pursue legal action against those acting in good faith. * Validating and acknowledging reports promptly, including an initial response and further investigation. * Addressing vulnerabilities in a timely manner. * Recognizing your contributions if you are the first to report a valid vulnerability that results in a code or configuration change. All decisions regarding eligibility, reward amounts, and payout determinations are made at Onyx’s sole discretion. Onyx reserves the right to reject submissions and modify the terms of this program at any time.