Crypto Deposit Address Guide

CROSSFX API · CRYPTO FUNDING

Get the address for stablecoin funding.

Request a supported stablecoin and blockchain combination and retrieve the deposit addresses CrossFX holds for your client.

The address lookup does not fund the transfer itself. After sending funds, report the blockchain transaction through Initiate Deposit using the same chain.

Stablecoin fundingChain-specificClient-scopedReusable addresses

How crypto funding starts

Choose the exact stablecoin and chain you intend to use. CrossFX returns the available deposit address entries for that combination.

01

Choose currency

currency_code

→

02

Choose chain

chain

→

03

Get address

Client-scoped wallet

→

04

Send funds

Use the same chain

→

05

Report deposit

Transaction hash + chain

Currency + chain

Request the exact combination

Deposit addresses are returned for the `currency_code` and `chain` you specify.

Client-scoped

Your addresses

The response contains addresses held for your CrossFX client rather than a shared address pool.

Reusable

Cache by combination

An address returned once can be funded again, so you can cache it by chain and currency.

Multiple entries

Expect a list

More than one wallet can serve a chain, so the response returns an array of address entries.

When to use the address API

Funding instructions

Show where to send

Present the correct stablecoin deposit address when funding a transfer.

Address caching

Avoid unnecessary lookups

Cache a valid address per currency and chain rather than requesting it for every transfer.

Multi-chain funding

Support available chains

If your integration supports several configured chains, let the funding flow select the appropriate one before retrieving an address.

Before you start

Authentication

Use a valid bearer token

See the Authentication Guide.

Supported currency & chain

Use configured values

You need a supported currency_code and chain.

See the Sandbox Data & Testing Guide for the combinations available in Sandbox.

Get crypto deposit addresses

List Crypto Deposit Addresses

Retrieve funding addresses

`POST /api/v1/crypto/deposit/address`

Open the API Reference for the complete request and response schemas and an interactive console.

REQUEST & RESPONSE

Send currency_code and chain in the request body.

A successful request returns HTTP 201 and data, a list of address entries.

HTTP SEMANTICS

This lookup uses POST and returns 201.

The currency and chain are sent in the request body rather than as query parameters. Treat 201 as the successful response for this operation.

Chain safety

The deposit address and blockchain network must always be treated as one combination.

CRITICAL FUNDING RULE

Send funds only on the chain you requested.

An address is monitored on its own chain. Funds sent to that address using a different chain are not recoverable through the API.

CORRECT

Same chain throughout

Request the address for a chain, send funds on that chain, then report the deposit using that same chain.

INCORRECT

Address on one chain, funds on another

Do not assume the same address representation means the funds can be sent over a different network.

Chain values are case-sensitive

chain must match one of the API's allowed values exactly.

ACCEPTED FORMAT

POLYGON

NOT EQUIVALENT

polygon

An unrecognised chain is treated as a validation error because the field has a fixed set of allowed values.

Getting an address does not create a deposit

This endpoint only tells you where to send funds.

ADDRESS

Retrieve destination

→

BLOCKCHAIN

Send stablecoins

→

DEPOSIT

Report transaction hash

→

TRANSFER

Funding progresses

After sending funds, call Initiate Deposit and provide the blockchain transaction hash together with the same chain.

Retrieving an address alone does not create a Deposit resource or change the transfer state.

Business rules

REQUEST

POST + 201

Send the currency and chain in the body and treat HTTP 201 as success.

CHAIN

Case-sensitive

Send the exact allowed value, such as POLYGON rather than polygon.

NETWORK

Keep the chain consistent

Request, fund and report the deposit using the same blockchain network.

DEPOSIT

Separate operation

Getting an address does not report or create the deposit. Initiate Deposit after the funds have been sent.

Currency and chain failures differ

An unknown currency and an unsupported chain do not produce the same response.

Unknown currency_code

404 · NOT_FOUND

`currency_code` is resolved against the CrossFX currency catalogue.

Use a supported stablecoin.

Unknown chain

422 · VALIDATION_FAILED

`chain` has a fixed set of allowed values.

Read `error.json` for the allowed chain values.

Errors

Every error below returns the CrossFX platform error envelope, with error first and error_id last.

SUPPORT IDENTIFIER

Keep the error_id

Quote the returned error_id when contacting CrossFX support so the failed address request can be located in platform logs.

HTTP	`code`	Trigger	What you do
422	`VALIDATION_FAILED`	`currency_code` or `chain` is missing or null, or `chain` is not an allowed value	Read `error.json`. The message lists the allowed chains.
422	`VALIDATION_FAILED`	The body carries a field the endpoint does not accept	Read `error.json` for the field name and remove it.
404	`NOT_FOUND`	`currency_code` is not a currency the platform knows	Use a supported stablecoin.
400	`BAD_REQUEST`	The upstream address provider returned an unusable response	Retry with backoff, then contact support.
500	`INTERNAL_ERROR`	The upstream address provider failed	Retry with backoff.
401	—	The `Authorization` header is missing, malformed, or the token has expired	Request a new token and retry. The body is `{ "message": "Unauthorized" }`.

Initiate Deposit Guide

Report the funding transaction

After sending stablecoins, report the transaction hash and chain to create the deposit leg.

Sandbox Data & Testing Guide

Use supported test values

See the stablecoins and blockchain networks available in Sandbox.

Generate Quote Guide

Start the transfer first

Only a quote issues the `cbtx_tracking_id` that the resulting deposit will fund.

How crypto funding starts#

When to use the address API#

Before you start#

Get crypto deposit addresses#

Chain safety#

Chain values are case-sensitive#

Getting an address does not create a deposit#

Business rules#

Currency and chain failures differ#

Errors#

Related#