Mirror Protocol Lifecycle

State machines for deposits, custody addresses, withdrawals, and completion. Executable steps are on the linked pages. Contract addresses are on Contracts.

Mainnet only. Base URL: https://mainnet-gw.sodex.dev/api/v1. There is no Testnet Mirror API.

Deposits

• Custody deposits credit the user's Spot account directly; no ValueChain EVM-to-Spot transfer is required. The first trading-account deposit must be USDC or SOSO (activation costs 1 unit).

• Bridge credits Spot when toClob is true, otherwise ValueChain EVM. Do not follow a toClob deposit with depositERC20.

• ValueChain → Spot/Perps is not an external deposit.

Use Asset Configuration to select the route and Deposit Status to track the saved source hash. A source-network receipt is not destination credit.

Custody addresses

Do not reuse an address across chainName or asset. The address object has only chain, address, and status — no memo/tag field. Do not invent a tag or derive one from the user's EVM address. If the destination network requires a memo or tag and it was not supplied with the custody assignment, do not open the transfer.

See Generate Custody Address for creation and the SoDexTokenCustody check.

Generate Custody AddressDeposit Addresses

Withdrawals

Coin in cmdData is canonical assetName. Route type is 0 (custody) or 1 (bridge). This is the Sponsored Withdrawal API, not the Transaction Relayer.

Perps funds move through Spot before ValueChain EVM. Each hop is asynchronous and must complete before the next begins. See Withdrawals.

History and Status

Persist source-chain hashes, the ValueChain request hash, and withdrawId so tracking can resume after a restart or timeout.

Deposit status

Query with the external chainName and source transaction hash. One hash can produce several records (n). A non-empty result means Gateway observed the transaction; inspect status before treating funds as available. If chain does not match, the API returns empty, not an error.

Confirm custody credit in the user's Spot balance. For bridge deposits, confirm the Spot balance when toClob is true, or the ValueChain EVM balance when it is false.

Withdrawal status

Query with chainName plus the ValueChain request txHash or withdrawId. Prefer withdrawId once it exists. Status txHash is not the final external-chain hash. Submission is not external completion.

History can filter by side, asset, chain, time window, and pending state. Persist txHash, originTxHash, and withdrawId when present.

Completion checks

These branches are integration decisions, not extra API status values.

Observation	What it establishes	What to do next
Deposit address is Enabled	API has a string.	Verify it in getDepositWalletList. Still not a credit.
Address is in getDepositWalletList	On-chain assignment matches.	Transfer may be opened. Still not a credit.
HTTP success or envelope code=0	The query or submission succeeded.	Inspect the transfer record.
Source transaction receipt succeeds	The source-chain transaction executed.	Keep tracking the cross-chain transfer.
Transfer is Processing	Not finished.	Poll; do not resubmit.
History query uses pending=false	The query asked for non-pending rows.	The filter is not delivery.
Unknown status, missing record, or query failure	Completion is not established.	Keep identifiers; retry the query.

Do not infer arrival from a transaction hash or from the absence of pending history. A terminal failure is not delivery.

Operational guidance

• Make status polling idempotent.

• Persist identifiers before waiting for settlement.

• Use bounded backoff and expose pending states.

• Reconcile the destination balance before retrying an ambiguous operation.

History & Status

Transfer guides

Custody DepositsBridge DepositsValueChain to Spot or PerpsWithdrawals