> For the complete documentation index, see [llms.txt](https://sodex.com/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sodex.com/documentation/for-developers/api-reference/mirror-api/asset-configuration.md). # Asset Configuration Returns the canonical asset metadata used by ValueChain and SoDEX, together with the supported external deposit and withdrawal chains, route availability, minimum amounts, fees, and optional estimated processing times. ## Endpoint ```http GET /api/v1/asset/config GET /api/v1/asset/config?name=USDC ``` Mainnet URL: ``` https://mainnet-gw.sodex.dev/api/v1/asset/config ``` Rate-limit weight: `0`. ## Terminology * **Asset** is the canonical user-facing asset, such as `USDC`, `ETH`, `SOSO`, or `CXMT`. * **ValueChain metadata** describes how the asset exists on ValueChain. It may be an ERC-20 token or a native ValueChain asset. * **SoDEX metadata** describes the asset registered in SoDEX/ClobGateway and its current market metadata. An asset can exist on ValueChain without being registered in SoDEX. * **External chain** is a chain from which users can deposit or to which users can withdraw, such as `ETH`, `BASE_ETH`, `SOL`, or `ARBITRUM_ETH`. * **Custody route** transfers assets through the custody service. * **Bridge route** transfers assets through a bridge contract. `chains` contains external-chain routes only. ValueChain itself is represented by `valueChainMetadata` and is not returned as a `chainName: "VALUECHAIN"` entry. ## Request ### Query Parameters | Name | Type | Required | Description | | ------ | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | `string` | `false` | Case-insensitive asset-name filter. Use the user-facing asset name, for example `USDC`, `ETH`, `SOSO`, or `CXMT`. Omit this parameter to return every asset. An unknown name returns an empty `data` array. | The old `coin` query parameter is no longer supported. Sending `coin=USDC` does not apply the new asset-name filter; clients must use `name=USDC`. ### Name Aliases The following aliases are handled by the API: | Requested `name` | Canonical returned `assetName` | Explanation | | ---------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | | `WSOSO` | `SOSO` | WSOSO is the ERC-20 wrapper of native SOSO on ValueChain. Its metadata is returned in `valueChainMetadata.wrappedToken`. | | `GRAM` | `TON` | `GRAM` is accepted as an alias. The canonical external asset name is `TON`, while the ValueChain/SoDEX token metadata may still use `vGRAM`. | Aliases and ordinary asset names are case-insensitive. For example, `name=usdc` and `name=USDC` return the same asset. ### Request Example ```bash curl \ "https://mainnet-gw.sodex.dev/api/v1/asset/config?name=USDC" \ -H "Accept: application/json" ``` ## Response Envelope Successful and failed responses use the same top-level envelope. Clients must check `code`; they must not rely on the HTTP status alone. | Name | Type | Required | Nullable | Description | | ----------- | --------------- | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `code` | `int32` | `true` | `false` | Gateway application status code. `0` means success. A non-zero value means the request could not be completed. | | `timestamp` | `uint64` | `true` | `false` | Time at which Gateway created the response, expressed as Unix time in milliseconds. | | `data` | `AssetConfig[]` | success only | `false` | Asset configurations. The array contains one element for a matched `name`, every asset when `name` is omitted, or zero elements when the name is unknown. Assets are sorted case-insensitively by `assetName`. This field is omitted on failure. | | `error` | `string` | failure only | `false` | Human-readable error message. This field is omitted on success. It is intended for diagnostics and must not be parsed as a stable machine-readable error code. | ## AssetConfig One `AssetConfig` describes a canonical asset across three scopes: ValueChain, SoDEX, and supported external chains. | Name | Type | Required | Nullable | Description | | -------------------- | -------------------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `assetName` | `string` | `true` | `false` | Canonical user-facing asset name, such as `USDC`, `ETH`, `SOSO`, `sSOSO`, `TON`, or `CXMT`. Use this value when displaying or selecting the asset. It is not necessarily the same as the ValueChain token symbol or SoDEX market name. | | `valueChainMetadata` | `ValueChainMetadata` | `true` | `false` | Metadata for the asset representation on ValueChain. This object is returned even when the asset is not registered in SoDEX or has no external-chain routes. | | `sodexMetadata` | `SoDEXMetadata` | `true` | `true` | SoDEX/ClobGateway registration and market metadata. `null` means Gateway could not match this ValueChain asset to a SoDEX asset. A `null` value does not prevent the asset from having deposit routes. | | `chains` | `ChainConfig[]` | `true` | `false` | External-chain deposit and withdrawal configurations. An empty array means the asset has metadata on ValueChain/SoDEX but currently exposes no external-chain transfer route through this API. | ## ValueChainMetadata Describes the asset token on ValueChain. | Name | Type | Required | Nullable | Description | | --------------- | ---------------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `tokenName` | `string` | `true` | `true` | Token name on ValueChain, for example `SoDexToken: USDC`. For a native ValueChain asset, this is the native asset name, for example `SOSO`. `null` means the token contract did not provide a usable name. | | `tokenSymbol` | `string` | `true` | `true` | Token symbol on ValueChain, for example `vUSDC`. For a native ValueChain asset, this is the native symbol, for example `SOSO`. `null` means the token contract did not provide a usable symbol. | | `tokenDecimals` | `uint8` | `true` | `false` | Number of decimal places used by the ValueChain token. Use it when converting ValueChain base-unit integer amounts to human-readable amounts. | | `evmAddress` | `string` | `false` | `false` | EVM contract address of the ValueChain ERC-20 token. This field is omitted when `isNativeToken` is `true`, because a native token has no ERC-20 contract address. | | `isNativeToken` | `bool` | `true` | `false` | Whether this asset is native to ValueChain. `true` means transfers use the ValueChain native asset rather than an ERC-20 contract; `false` means `evmAddress` identifies the ERC-20 contract. | | `wrappedToken` | `WrappedTokenMetadata` | `false` | `false` | ERC-20 wrapper metadata for a native ValueChain asset. This field is omitted when the asset is not native or no registered wrapper exists. For SOSO, it describes WSOSO. | ### WrappedTokenMetadata Describes the ERC-20 wrapper associated with a native ValueChain asset. | Name | Type | Required | Nullable | Description | | --------------- | -------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `tokenName` | `string` | `true` | `true` | Wrapper token name, for example `Wrapped SOSO`. `null` means the wrapper contract did not provide a usable name. | | `tokenSymbol` | `string` | `true` | `true` | Wrapper token symbol, for example `WSOSO`. `null` means the wrapper symbol is unavailable. | | `tokenDecimals` | `uint8` | `true` | `false` | Wrapper token decimals used for base-unit conversion. | | `evmAddress` | `string` | `true` | `false` | ValueChain EVM contract address of the wrapper token. This is the address integrations use for ERC-20 interactions with the wrapper. | ## SoDEXMetadata Describes the SoDEX/ClobGateway asset matched to the ValueChain asset. | Name | Type | Required | Nullable | Description | | ------------- | ---------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | `uint64` | `true` | `false` | SoDEX/ClobGateway asset ID. `0` is a valid ID, for example for USDC, and must not be treated as missing. Asset IDs should be used when another SoDEX API explicitly requires an asset ID. | | `name` | `string` | `true` | `false` | SoDEX market/coin name, for example `vUSDC`, `WSOSO`, or `aCXMT`. This can differ from top-level `assetName`. | | `tokenPrice` | decimal `string` | `true` | `true` | Current SoDEX reference price returned as a decimal string in the market's quote denomination. It is `null` when the market price is unavailable or not initialized. Prices are dynamic and examples in this document are illustrative only. | | `marginRatio` | decimal `string` | `true` | `true` | SoDEX margin/collateral ratio expressed as a decimal string. For example, `0.9` represents a ratio of 90%. `0` is a valid configured value; `null` means market metadata is unavailable. This field is not a transfer fee and must not be used to calculate deposit or withdrawal costs. | `sodexMetadata: null` means there is no address-matched SoDEX asset. Clients must check for `null` before accessing any nested field. ## ChainConfig Describes one external-chain representation of the asset and the available transfer methods on that chain. | Name | Type | Required | Nullable | Description | | --------------- | ----------------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `chainName` | `string` | `true` | `false` | Gateway chain identifier, for example `ETH`, `BASE_ETH`, `ARBITRUM_ETH`, `SOL`, or `TON`. Use this exact value in deposit-address, history, or other transfer APIs that accept a `chain` parameter. | | `isNativeToken` | `bool` | `true` | `false` | Whether the asset is the native token of this external chain. For example, ETH on the Ethereum chain and SOL on Solana are native. This flag describes the external-chain representation and is independent of `valueChainMetadata.isNativeToken`. | | `tokenAddress` | `string` | `false` | `false` | Token contract or token identifier on the external chain. It can be an EVM address, Solana mint address, or another chain-specific identifier. It is omitted when `isNativeToken` is `true`; omission does not mean the route is unavailable. | | `bridge` | `BridgeMetadata` | `false` | `false` | Bridge route configuration. Omitted when no bridge route is configured for this asset and chain. When present, check `allowDeposit` and `allowWithdraw` separately. | | `custody` | `CustodyMetadata` | `false` | `false` | Custody route configuration. Omitted when no custody metadata exists. When present, the route may still be disabled; check `allowDeposit` and `allowWithdraw` separately. | ## BridgeMetadata Describes deposit and withdrawal through a bridge contract. | Name | Type | Required | Nullable | Description | | -------------------------- | ---------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `bridgeAddress` | `string` | `true` | `false` | Bridge contract address used for this route. The entire `bridge` object is omitted instead of returning an empty address when the bridge route does not exist. | | `minDepositAmount` | decimal `string` | `true` | `false` | Configured minimum bridge deposit in human-readable units of `assetName`. For example, `"5"` for USDC means 5 USDC, not 5 base units. Always check `allowDeposit`; the presence of this amount alone does not prove deposits are enabled. | | `minWithdrawAmount` | decimal `string` | `false` | `false` | Minimum bridge withdrawal in human-readable asset units. Omitted when `allowWithdraw` is `false`. When `allowWithdraw` is `true`, clients should require the requested amount to meet this minimum. | | `withdrawFee` | decimal `string` | `false` | `false` | Bridge withdrawal fee in human-readable asset units. Omitted when `allowWithdraw` is `false`. An explicit `"0"` means zero fee; an empty string means no usable fee was supplied and must not automatically be interpreted as zero. | | `allowDeposit` | `bool` | `true` | `false` | Whether bridge deposits are currently enabled for this asset and chain. This is the authoritative bridge-deposit availability flag. | | `allowWithdraw` | `bool` | `true` | `false` | Whether bridge withdrawals are currently enabled for this asset and chain. This is independent of `allowDeposit`; a route may be deposit-only. | | `estimatedDepositSeconds` | `uint64` | `false` | `false` | Estimated bridge deposit completion time in seconds. Omitted when no estimate is available. It is an estimate, not a confirmation guarantee or SLA. | | `estimatedWithdrawSeconds` | `uint64` | `false` | `false` | Estimated bridge withdrawal completion time in seconds. Omitted when no estimate is available or withdrawals are disabled. It is an estimate, not a confirmation guarantee or SLA. | ## CustodyMetadata Describes deposit and withdrawal through the custody service. | Name | Type | Required | Nullable | Description | | -------------------------- | ---------------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `minDepositAmount` | decimal `string` | `true` | `false` | Configured minimum custody deposit in human-readable units of `assetName`. This field can still be present when `allowDeposit` is `false`; clients must use `allowDeposit`, not the presence of this value, to determine availability. | | `minWithdrawAmount` | decimal `string` | `false` | `false` | Minimum custody withdrawal in human-readable asset units. Omitted when `allowWithdraw` is `false`. | | `withdrawFee` | decimal `string` | `false` | `false` | Custody withdrawal fee in human-readable asset units. Omitted when `allowWithdraw` is `false`. An explicit `"0"` means zero fee; an empty string means the fee is unavailable and must not automatically be interpreted as zero. | | `allowDeposit` | `bool` | `true` | `false` | Whether custody deposits are currently enabled for this asset and chain. This is the authoritative custody-deposit availability flag. | | `allowWithdraw` | `bool` | `true` | `false` | Whether custody withdrawals are currently enabled for this asset and chain. This is independent of `allowDeposit`; a route may be deposit-only. | | `estimatedDepositSeconds` | `uint64` | `false` | `false` | Estimated custody deposit completion time in seconds. Omitted when no estimate is available. It is informational and not a confirmation guarantee or SLA. | | `estimatedWithdrawSeconds` | `uint64` | `false` | `false` | Estimated custody withdrawal completion time in seconds. Omitted when no estimate is available or withdrawals are disabled. It is informational and not a confirmation guarantee or SLA. | ## Transfer Route Availability Do not infer route availability from an address, fee, minimum amount, or ETA field. Use the route object and its explicit allow flags. | Operation | Available when | | ------------------ | ----------------------------------------------------------- | | Bridge deposit | `bridge` is present and `bridge.allowDeposit` is `true`. | | Bridge withdrawal | `bridge` is present and `bridge.allowWithdraw` is `true`. | | Custody deposit | `custody` is present and `custody.allowDeposit` is `true`. | | Custody withdrawal | `custody` is present and `custody.allowWithdraw` is `true`. | Important consequences: * Deposit and withdrawal availability are independent. A route can allow deposits while withdrawals are disabled. * A missing `bridge` or `custody` object means that transfer method is not configured for that chain. * `tokenAddress` being omitted means the asset is native on that external chain; it does not mean deposits or withdrawals are unavailable. * `minDepositAmount` can be returned for a disabled deposit route. Always check `allowDeposit` first. * Withdrawal-only fields are omitted when `allowWithdraw` is `false`. * `chains: []` means there is currently no external transfer route exposed for the asset. ## Decimal Amount and Fee Handling All prices, ratios, minimum amounts, and fees are returned as decimal strings to avoid floating-point precision loss. * Treat these fields as arbitrary-precision decimal values, not JavaScript `number` or binary floating-point values. * Amounts and fees are already expressed in human-readable asset units. For example, `"0.01"` for ETH means 0.01 ETH. * Do not apply `valueChainMetadata.tokenDecimals` to these decimal strings. That decimals field is used for ValueChain base-unit integer amounts, while API minimums and fees are already formatted. * Distinguish an omitted field, `null`, an empty string, and the explicit decimal string `"0"`; they do not have the same meaning. ## Successful Response Example: USDC The market price and response timestamp are dynamic. Other configuration values can also change over time; integrations should query the endpoint instead of hard-coding this example. ```json { "code": 0, "timestamp": 1786003839247, "data": [ { "assetName": "USDC", "valueChainMetadata": { "tokenName": "SoDexToken: USDC", "tokenSymbol": "vUSDC", "tokenDecimals": 6, "evmAddress": "0xcb7F80Dff2727c791fA491722c428e6657f7e2c6", "isNativeToken": false }, "sodexMetadata": { "id": 0, "name": "vUSDC", "tokenPrice": "1", "marginRatio": "1" }, "chains": [ { "chainName": "ARBITRUM_ETH", "isNativeToken": false, "tokenAddress": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", "custody": { "minDepositAmount": "5", "minWithdrawAmount": "5", "withdrawFee": "1", "allowDeposit": true, "allowWithdraw": true } }, { "chainName": "BASE_ETH", "isNativeToken": false, "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "custody": { "minDepositAmount": "5", "minWithdrawAmount": "5", "withdrawFee": "1", "allowDeposit": true, "allowWithdraw": true } }, { "chainName": "BSC_BNB", "isNativeToken": false, "tokenAddress": "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d", "custody": { "minDepositAmount": "5", "minWithdrawAmount": "5", "withdrawFee": "1", "allowDeposit": true, "allowWithdraw": true } }, { "chainName": "ETH", "isNativeToken": false, "tokenAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "custody": { "minDepositAmount": "5", "minWithdrawAmount": "5", "withdrawFee": "1", "allowDeposit": true, "allowWithdraw": true } }, { "chainName": "MATIC", "isNativeToken": false, "tokenAddress": "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359", "custody": { "minDepositAmount": "5", "minWithdrawAmount": "2", "withdrawFee": "1", "allowDeposit": true, "allowWithdraw": true } }, { "chainName": "SOL", "isNativeToken": false, "tokenAddress": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "custody": { "minDepositAmount": "5", "minWithdrawAmount": "5", "withdrawFee": "1", "allowDeposit": true, "allowWithdraw": true } } ] } ] } ``` ## Native Asset and Wrapper Example: SOSO / WSOSO Querying either `name=SOSO` or `name=WSOSO` returns the canonical SOSO asset. SOSO is native on ValueChain, so `valueChainMetadata.evmAddress` is omitted. WSOSO is returned as its ERC-20 wrapper. ```json { "assetName": "SOSO", "valueChainMetadata": { "tokenName": "SOSO", "tokenSymbol": "SOSO", "tokenDecimals": 18, "isNativeToken": true, "wrappedToken": { "tokenName": "Wrapped SOSO", "tokenSymbol": "WSOSO", "tokenDecimals": 18, "evmAddress": "0x5050505050505050505050505050505050505050" } }, "sodexMetadata": { "id": 4, "name": "WSOSO", "tokenPrice": "0.3576602227883511", "marginRatio": "0.5" }, "chains": [ { "chainName": "BASE_ETH", "isNativeToken": false, "tokenAddress": "0x624e2e7fDc8903165F64891672267AB0FCB98831", "bridge": { "bridgeAddress": "0xCC7322A2f9f82251dA51584B1a89915dBc02185B", "minDepositAmount": "1", "allowDeposit": true, "allowWithdraw": false }, "custody": { "minDepositAmount": "1", "allowDeposit": true, "allowWithdraw": false } }, { "chainName": "ETH", "isNativeToken": false, "tokenAddress": "0x76A0e27618462bDAC7a29104bdcfFf4E6BFCea2D", "bridge": { "bridgeAddress": "0xCC7322A2f9f82251dA51584B1a89915dBc02185B", "minDepositAmount": "1", "allowDeposit": true, "allowWithdraw": false }, "custody": { "minDepositAmount": "1", "allowDeposit": true, "allowWithdraw": false } } ] } ``` ## Other Important Response Cases The snippets in this section show only the fields relevant to each case. They are not complete `AssetConfig` objects; fields marked as required in the tables above are still returned by the API. ### Asset not registered in SoDEX An asset can have ValueChain or external-chain metadata without a matching SoDEX asset: ```json { "assetName": "sSOSO", "valueChainMetadata": { "tokenName": "Staked SOSO", "tokenSymbol": "sSOSO", "tokenDecimals": 18, "evmAddress": "0xb04eB6b64137d1673D46731C8f84718092c50B0D", "isNativeToken": false }, "sodexMetadata": null } ``` Do not treat the top-level asset as invalid solely because `sodexMetadata` is `null`. ### Asset with no external transfer route Metadata-only assets use an empty `chains` array: ```json { "assetName": "CXMT", "chains": [] } ``` The empty array means no external deposit or withdrawal route is currently exposed. It does not mean the ValueChain or SoDEX asset metadata is invalid. ### Deposit-only route When a route allows deposits but not withdrawals, withdrawal-only fields are omitted: ```json { "minDepositAmount": "1", "allowDeposit": true, "allowWithdraw": false } ``` Clients must not expect `minWithdrawAmount`, `withdrawFee`, or `estimatedWithdrawSeconds` in this case. ## Error Response Example Gateway currently returns the standard response envelope with `data` omitted on an application error. The exact `error` text depends on the underlying failure and is not a stable value for application logic: ```json { "code": -1, "timestamp": 1786003839247, "error": "failed to query transfer configuration" } ```