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

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

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.

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

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "code": -1,
  "timestamp": 1786003839247,
  "error": "failed to query transfer configuration"
}