sumsub-resolve-currency

Sumsub — Resolve currency and chain

One endpoint answers both halves, and the two halves look nothing alike:

Most of this skill is about the crypto side, because that is where transactions silently go wrong. Fiat is a membership test.

Endpoint

Omit type and you get the fiat list. There is no public endpoint for the chain list — derive it from the crypto catalogue's distinct cryptoChain values. There is no rates endpoint: Sumsub converts internally and does not expose the rate it used.

Each crypto entry carries currencyCode, cryptoChain, contractAddress, chainId, name, coinmarketcapId, coingeckoId.

Auth — App Token + secret (sandbox only)

Signing per the authentication reference; mechanics in `sumsub-api-auth`.

⚠️ Sandbox tokens only. The helper script refuses tokens that don't start with sbx: unless SUMSUB_ALLOW_PROD=1. This endpoint is read-only, but the same rule applies across these skills — get a sandbox pair at <https://cockpit.sumsub.com/checkus/home?sbx=true> (Connect Sumsub to your AI agent -> Build & configure -> Generate token).

The rule that matters

A symbol is not an asset. USDT and USDC each name more than a dozen different assets in the catalogue; ETH several. The identity of a crypto asset is the pair (currencyCode, cryptoChain), plus contractAddress when even that is not unique.

📘 An empty `cryptoChain` is a value, not a gap. It means the native coin of its own chain — BTC with no chain is bitcoin; BTC with cryptoChain: BTC is the same thing (the server normalises that common mistake); BTC on some wrapped chain is a different asset entirely.

🚧 Ambiguity does not resolve to a default — it resolves to nothing. When a lookup matches more than one row the server logs Multiple currencies found and returns no currency at all. So the symptom of a missing chain is not "wrong rate" but "currency not recognised", with everything downstream that depends on it silently degraded.

Procedure

1. Decide the type. If the code is three uppercase letters and appears in

the fiat list, treat it as fiat unless the user says otherwise. Beware of overlaps in intent — a user saying "USD" almost never means a token called USD.

1. Fetch the catalogue with ${CLAUDE_SKILL_DIR}/scripts/get_currencies.sh crypto

(or fiat). Cache it for the session; the crypto list is large and static.

1. Resolve with ${CLAUDE_SKILL_DIR}/scripts/resolve_currency.py — pass the

catalogue and the query. It uppercases and trims, expands chain aliases, treats code == chain as the native coin, and on ambiguity fails with the candidate list instead of picking one.

1. Report the exact fields to send, never just "supported":

   "info": {
     "currencyCode": "USDT",
     "currencyType": "crypto",
     "cryptoParams": { "cryptoChain": "TRX" }
   }

1. Address the conversion — see below. This is the part callers forget.

amountInDefaultCurrency — read this before skipping it

info.amountInDefaultCurrency + info.defaultCurrencyCode express the transfer in your reporting currency. They look optional. They are not, in three ways.

🚧 Travel Rule thresholds are compared against `amountInDefaultCurrency`. If it is absent, the threshold comparison is skipped entirely and the Travel Rule flow runs regardless of how small the transfer is. Omitting the field does not lose precision — it changes behaviour. The same applies to the unhosted-wallet verification threshold.

🚧 The value is frozen at ingest. Sumsub computes it once, when the transaction is created, and stores it. A rate that was wrong at that moment stays wrong on the record; correcting it later means a backfill, not a re-read.

📘 If the asset does not resolve, there is nothing to convert. An unrecognised (symbol, chain) pair means no conversion happens — which is the second reason a missing cryptoChain is expensive.

Recommendation: if you know the value your own systems used, send amountInDefaultCurrency and defaultCurrencyCode explicitly. Your books and Sumsub's record then agree by construction, and you are not depending on a third-party rate at an instant you do not control.

Chain aliases

Chain names are uppercased, trimmed, then mapped through a fixed alias table before lookup. ETHEREUM, BSC, TRC20, MATIC, POLYGON, BEP20, TRON, SOLANA, AVAX_C and about two dozen more resolve to their canonical chain. Anything outside the table is used verbatim, so a near-miss like TRON20 or ERC-20 simply does not match.

The table is not exposed by any endpoint — the full list is in `references/crypto-catalogue.md`. When a user's chain string fails to resolve, check it against the aliases before concluding the asset is unsupported.

Travel Rule specifics

Beyond the threshold behaviour above, the asset you pick can decide whether an exchange is possible at all. Each catalogue entry carries the counterparty protocols' own vocabularies, and coverage is thin.

Only a minority of catalogue entries carry a mapping for any given protocol — Sygna covers the most, then GTR, then CODE, and all three are a small fraction of the whole. Coverage grows as the weekly listing job picks up new assets, so check rather than assume.

An asset with no mapping for the protocol your counterparty speaks cannot be expressed in their message. The exchange fails validation before anything is sent — surfacing as notEnoughCounterpartyData, which reads like a data problem rather than an asset-support problem. If a Travel Rule exchange fails that way on an exotic token, check the vocabulary coverage before debugging the payload. See `sumsub-integrate-travel-rule`.

Outputs

• Resolved — the matched entry, and the exact currencyCode / currencyType / cryptoChain to send. Mention contractAddress when the symbol is a known collision, so the caller can pin it.
• Ambiguous — the candidate rows with their chains and contracts, and the question the user must answer. Never pick one.
• Not found — say whether the symbol is unknown or only the chain is, and check the alias table before declaring it unsupported.

Worked examples

• `examples/resolve-usdt-tron.json` — the common case: a collided symbol pinned by chain.
• `examples/resolve-ambiguous.json` — the same symbol with no chain; must fail, not guess.
• `examples/resolve-native.json` — a native coin, showing the empty-chain semantics.
• `examples/resolve-fiat.json` — the membership test.

See also

• `references/crypto-catalogue.md` — catalogue fields, the alias table, the server's resolution ladder, collision statistics.
• `sumsub-create-transaction` — where the resolved fields go.
• `sumsub-integrate-travel-rule` — thresholds and protocol vocabularies.