CryptoConnect Integration for Gateway Mode

• This guide provides the end-to-end workflow for Gateway mode integration with CryptoConnect.

• Before starting the integration, confirm your operating model: MoR (Merchant of Record) or Gateway Mode. Refer to the official documentation for guidance: Determine Your Integration Model.

Generate a Wallet Address

This section explains how to generate and retrieve crypto wallet addresses for your users, which is the first step to enabling crypto deposits.

In Gateway Mode, once KYC is approved, a set of master wallets is provisioned by default.

Step 1 — Get wallet addresses

Use the List all wallets API to fetch wallet information, including balances and available addresses.

⚠️
Note: The request must include the account ID parameter.

Request Example

# Replace ${YOUR_API_ACCESS_TOKEN} with your API access token
curl --request GET \
     --url https://api-sandbox.interlace.money/open-api/v2/cryptoconnect/wallets?accountId=b27c8873-e400-47cd-adc1-035cfa0d5347 \
     --header 'accept: application/json' \
     --header 'x-access-token: ${YOUR_API_ACCESS_TOKEN}'

Response Example

{
    "code": 0,
    "message": "ok",
    "data": {
        "data": [
            {
                "id": "04314cd3-1cc1-4bff-9398-be86f99041a0",
                "idempotencyKey": "22b54be7-44ec-40eb-9509-aa650f65570f",
                "accountId": "2aeafea5-0929-4bd4-91dc-fd1bbf4c101e",
                "nickname": "Master Wallet",
                "master": true,
                "balances": [
                    {
                        "id": "4eb7db5e-d57b-4d78-94e4-a621c74cffba",
                        "currency": "ETH",
                        "available": "0",
                        "frozen": "0"
                    }
                ],
                "addresses": []
            },
            {
                "id": "5e802715-ddf7-443a-b34f-a324f91ab549",
                "idempotencyKey": "b79500cd-34f2-4ceb-bde7-7fb98136e1c3",
                "accountId": "2aeafea5-0929-4bd4-91dc-fd1bbf4c101e",
                "nickname": "Master Wallet",
                "master": true,
                "balances": [
                    {
                        "id": "95d9df48-52c7-469a-b9a2-ad0dcf1f616c",
                        "currency": "BTC",
                        "available": "0",
                        "frozen": "0"
                    }
                ],
                "addresses": []
            },
            {
                "id": "c25a30d6-2f1a-4534-8133-5a80f8ffae42",
                "idempotencyKey": "1abdc6ff-dfd8-4266-ab77-b6a757e2cda0",
                "accountId": "2aeafea5-0929-4bd4-91dc-fd1bbf4c101e",
                "nickname": "Master Wallet",
                "master": true,
                "balances": [
                    {
                        "id": "e7189e74-936e-44a1-94a7-2b28e3ad6eb3",
                        "currency": "USDT",
                        "available": "0",
                        "frozen": "0"
                    }
                ],
                "addresses": []
            },
            {
                "id": "785a98b0-057a-4a30-bbd2-40ea101f4d41",
                "idempotencyKey": "52470e3f-1fe9-407e-a2c5-b6493bb654b1",
                "accountId": "2aeafea5-0929-4bd4-91dc-fd1bbf4c101e",
                "nickname": "Master Wallet",
                "master": true,
                "balances": [
                    {
                        "id": "4993d9c6-122a-403a-a22e-7aee9d5480b0",
                        "currency": "USDC",
                        "available": "0",
                        "frozen": "0"
                    }
                ],
                "addresses": []
            }
        ],
        "total": 5,
        "pageTotal": 5
    }
}

Step 2 — Generate an additional address (optional)

If no address is available, or if you need an address on a different blockchain, use the Create a blockchain address API to generate a new one.

⚠️
Note: The request must include the wallet ID parameter.

Request Example

# Replace ${YOUR_API_ACCESS_TOKEN} with your API access token
curl --request POST \
     --url https://api-sandbox.interlace.money/open-api/v2/cryptoconnect/wallets/32aae8b7-4a69-474f-b7d5-337e190af878/addresses \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-access-token: ${YOUR_API_ACCESS_TOKEN}' \
     --data '{
         "currency": "USDC",
         "chain": "ETH"
     }'

Response Example

{
    "code": 0,
    "message": "ok",
    "data": {
        "walletId": "785a98b0-057a-4a30-bbd2-40ea101f4d41",
        "currency": "USDC",
        "chain": "ETH",
        "address": "0xc63e94534913e846c2aa72f6000684f53ea61859",
        "selected": true
    }
}

Deposit Crypto to Infinity Account (Stablecoin Top-up)

After a user deposits crypto to a generated wallet address, you can transfer the funds to your Infinity Account for easier access and use.

📘
Notes: Steps 1 and 3 are optional. They provide flexibility in how funds are routed. You may choose to move balances at CryptoConnect Wallet layer (stablecoins) or at Infinity Account layer (USD), depending on your business flow.

Step 1 — Transfer between CryptoConnect Wallets (optional)

After receiving the deposit webhook notification, use the Create a transfer API to move stablecoins from a Sub-Merchant Wallet to the Master Merchant Wallet.

Request Example

# Replace ${YOUR_API_ACCESS_TOKEN} with your API access token
curl --request POST \
     --url https://api-sandbox.interlace.money/open-api/v1/asset/transfers \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-access-token: ${YOUR_API_ACCESS_TOKEN}' \
     --data '{
         "source": {
             "type": "crypto_assets",
						 "id": "2aeafea5-0929-4bd4-91dc-fd1bbf4c101e",
             "currency": "USDC",
         },
         "destination": {
             "currency": "USDC",
             "type": "crypto_assets"
         },
         "amount": "1"
     }'

Response Example

{
    "code": 0,
    "message": "ok",
    "data": {
        "id": "1cf2f4be-39c2-4793-b6a9-0bdc8a8b2fd0",
        "accountId": "2aeafea5-0929-4bd4-91dc-fd1bbf4c101e",
        "source": {
            "type": "crypto_assets",
            "id": "2aeafea5-0929-4bd4-91dc-fd1bbf4c101e",
            "currency": "USDC"
        },
        "destination": {
            "type": "crypto_assets",
            "id": "b27c8873-e400-47cd-adc1-035cfa0d5347",
            "currency": "USDC"
        },
        "amount": {
            "amount": "1",
            "currency": "USDC"
        },
        "settled": {
            "amount": "1",
            "currency": "USDC"
        },
        "fee": {
            "amount": "0",
            "currency": "USDC"
        },
        "status": "Closed",
        "createTime": "2025-09-22T08:28:06.663Z",
        "updateTime": "2025-09-22T08:28:09.136Z"
    }
}

Step 2 — Deposit to Sub-Merchant Infinity Account

Use the Create a transfer API to move USDC or USDT from a Sub-Merchant Wallet to the Sub-Merchant Infinity Account.

Request Example

# Replace ${YOUR_API_ACCESS_TOKEN} with your API access token
curl --request POST \
     --url https://api-sandbox.interlace.money/open-api/v1/asset/transfers \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-access-token: ${YOUR_API_ACCESS_TOKEN}' \
     --data '{
         "source": {
             "type": "crypto_assets",
             "id": "2aeafea5-0929-4bd4-91dc-fd1bbf4c101e",
             "currency": "USDC"
         },
         "destination": {
         		 "type": "quantum_sub_account",
             "id": "2aeafea5-0929-4bd4-91dc-fd1bbf4c101e"
         },
         "amount": "10"
     }'

Response Example

{
    "code": 0,
    "message": "ok",
    "data": {
        "id": "b74a09f7-bca1-49fc-b2cb-47ce0299723f",
        "accountId": "2aeafea5-0929-4bd4-91dc-fd1bbf4c101e",
        "source": {
            "type": "crypto_assets",
            "id": "2aeafea5-0929-4bd4-91dc-fd1bbf4c101e",
            "currency": "USDC"
        },
        "destination": {
            "type": "quantum_sub_account"
        },
        "amount": {
            "amount": "10.00",
            "currency": "USDC"
        },
        "status": "Pending",
        "createTime": "2025-09-22T08:41:41.773Z",
        "updateTime": "2025-09-22T08:41:41.773Z"
    }
}

Step 3 — Transfer between Infinity Accounts (optional)

Use the Create a transfer API to move funds from the Sub-Merchant Infinity Account to the Master Merchant Infinity Account.

Request Example

# Replace ${YOUR_API_ACCESS_TOKEN} with your API access token
curl --request POST \
     --url https://api-sandbox.interlace.money/open-api/v1/asset/transfers \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-access-token: ${YOUR_API_ACCESS_TOKEN}' \
     --data '{
         "destination": {
         		 "type": "quantum_sub_account",
             "id": "2aeafea5-0929-4bd4-91dc-fd1bbf4c101e"
         },
         "source": {
             "type": "quantum_account"
         },
         "amount": "1"
     }'

Response Example

{
    "code": 0,
    "message": "ok",
    "data": {
        "id": "511ebdd1-29a2-4d6f-8d6d-5a8f0de80a4d",
        "accountId": "b27c8873-e400-47cd-adc1-035cfa0d5347",
        "source": {
            "type": "quantum_account"
        },
        "destination": {
            "type": "quantum_sub_account",
            "id": "2aeafea5-0929-4bd4-91dc-fd1bbf4c101e"
        },
        "amount": {
            "amount": "1",
            "currency": "USD"
        },
        "settled": {
            "amount": "1",
            "currency": "USD"
        },
        "fee": {
            "amount": "0",
            "currency": "USD"
        },
        "status": "Closed",
        "createTime": "2025-09-22T08:46:27.774Z",
        "updateTime": "2025-09-22T08:46:27.774Z"
    }
}

Step 4 — Funds Available

Once credited, funds can be used for:

Issuing cards
Prepaid card top-ups
Budget allocations

Convert & Withdraw Crypto (Redemption and Withdrawal)

To withdraw funds from your Infinity Account to an external wallet, follow these steps.

Step 1 — Move USD to CryptoConnect Wallet

Use the Create a transfer API to transfer USD from Sub-Merchant Infinity Account into Sub-Merchant CryptoConnect Wallet.

Request Example

# Replace ${YOUR_API_ACCESS_TOKEN} with your API access token
curl --request POST \
     --url https://api-sandbox.interlace.money/open-api/v1/asset/transfers \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-access-token: ${YOUR_API_ACCESS_TOKEN}' \
     --data '{
         "source": {
             "type": "quantum_sub_account",
             "id": "2aeafea5-0929-4bd4-91dc-fd1bbf4c101e"
         },
         "destination": {
             "type": "crypto_assets",
             "id": "2aeafea5-0929-4bd4-91dc-fd1bbf4c101e",
             "currency": "USD"
         },
         "amount": "5"
     }'

Response Example

{
    "code": 0,
    "message": "ok",
    "data": {
        "id": "8a273503-ecfa-413a-84fa-42508f268f95",
        "accountId": "2aeafea5-0929-4bd4-91dc-fd1bbf4c101e",
        "source": {
            "type": "quantum_sub_account",
            "id": "2aeafea5-0929-4bd4-91dc-fd1bbf4c101e"
        },
        "destination": {
            "type": "crypto_assets",
            "id": "2aeafea5-0929-4bd4-91dc-fd1bbf4c101e",
            "currency": "USD"
        },
        "amount": {
            "amount": "5",
            "currency": "USD"
        },
        "settled": {
            "amount": "5",
            "currency": "USD"
        },
        "fee": {
            "amount": "0",
            "currency": "USD"
        },
        "status": "Closed",
        "createTime": "2025-09-22T08:48:37.888Z",
        "updateTime": "2025-09-22T08:48:36.191Z"
    }
}

Step 2 — Preview exchange rates and fees (optional)

Use the Get an estimate quote API to check rates and fees before conversion.

📘
Note: If skipped, the system will automatically request a quote in Step 3.

Request Example

# Replace ${YOUR_API_ACCESS_TOKEN} with your API access token
curl --request POST \
     --url https://api-sandbox.interlace.money/open-api/v2/cryptoconnect/convert/estimate-quote \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-access-token: ${YOUR_API_ACCESS_TOKEN}' \
     --data '{
         "accountId": "2aeafea5-0929-4bd4-91dc-fd1bbf4c101e",
         "baseCurrency": "USDC",
         "quoteCurrency": "USD",
         "side": "buy",
         "rfqCurrency": "USD",
         "rfqAmount": "5"
     }'

Response Example

{
    "code": 0,
    "message": "ok",
    "data": {
        "id": "349a5d2e-6fb2-401e-9d5a-f4ee7f39ba12",
        "quoteTime": "1758531010058",
        "baseCurrency": "USDC",
        "baseAmount": "4.975",
        "quoteCurrency": "USD",
        "quoteAmount": "5",
        "side": "buy",
        "rate": "1",
        "rfqAmount": "5",
        "rfqCurrency": "USD",
        "fee": "0.025",
        "feeCurrency": "USD",
        "ttlMs": "60000"
    }
}

Step 3 — Convert USD to crypto

Use the Create a trade API to exchange USD for USDC/USDT.

📘
Note: Currently only conversions between USD ↔ USDC/USDT and USDC ↔ USDT are supported.

Request Example

# Replace ${YOUR_API_ACCESS_TOKEN} with your API access token
curl --request POST \
     --url https://api-sandbox.interlace.money/open-api/v2/cryptoconnect/convert/trades \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-access-token: ${YOUR_API_ACCESS_TOKEN}' \
     --data '{
         "idempotencyKey": "e27be9f8-2d59-4aa7-a9fd-f5571927637d",
         "accountId": "2aeafea5-0929-4bd4-91dc-fd1bbf4c101e",
         "baseCurrency": "USDC",
         "quoteCurrency": "USD",
         "side": "buy",
         "rfqCurrency": "USD",
         "rfqAmount": "5"
     }'

Response Example

{
    "code": 0,
    "message": "ok",
    "data": {
        "id": "ff47fe65-4285-41db-8386-bf7fd471e987",
        "accountId": "2aeafea5-0929-4bd4-91dc-fd1bbf4c101e",
        "symbol": "USDC-USD",
        "baseWalletId": "785a98b0-057a-4a30-bbd2-40ea101f4d41",
        "baseCurrency": "USDC",
        "baseAmount": "4.975",
        "quoteCurrency": "USD",
        "quoteAmount": "5",
        "side": "buy",
        "rate": "1",
        "fee": "0.025",
        "feeCurrency": "USD",
        "status": "Closed",
        "idempotencyKey": "ad7009f2-5105-499a-88bb-722160af6a95",
        "createTime": "1758531064160",
        "updateTime": "1758531065089",
        "completeTime": "1758531065084"
    }
}

Step 4 — Preview withdrawal fees (optional)

Use the Get transfer fee API to check fees before withdrawal.

📘
Note: If skipped, fees will be retrieved automatically in Step 5.

Request Example

# Replace ${YOUR_API_ACCESS_TOKEN} with your API access token
curl --request POST \
     --url https://api-sandbox.interlace.money/open-api/v2/cryptoconnect/transfers/fee-and-quota \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-access-token: ${YOUR_API_ACCESS_TOKEN}' \
     --data '{
         "accountId": "2aeafea5-0929-4bd4-91dc-fd1bbf4c101e",
         "source": {
             "type": "cryptoconnect_wallet",
             "id": "785a98b0-057a-4a30-bbd2-40ea101f4d41"
         },
         "destination": {
             "type": "blockchain",
             "chain": "ETH",
             "address": "0x89F9Cfaa0dA076351DdfC6E320bD8df8b538dB17"
         },
         "amount": {
             "amount": "15",
             "currency": "USDC"
         }
     }'

Response Example

{
    "code": 0,
    "message": "ok",
    "data": {
        "crossChainQuota": "0",
        "crossChainFeeRate": "0.003",
        "crossChainAmount": "15",
        "fees": [
            {
                "amount": "9",
                "currency": "USDC",
                "type": "GAS"
            },
            {
                "amount": "0.05",
                "currency": "USDC",
                "type": "CROSS_CHAIN"
            }
        ]
    }
}

Step 5 — Withdraw crypto

Use the Create a blockchain transfer API to withdraw crypto to an external wallet.

⚠️
Note: Ensure that both the wallet address and the blockchain network are correctly specified before initiating the withdrawal.

Withdrawal Status Flow 💰

When you initiate a withdrawal, Interlace first receives the request and assigns it a status of Pending, with the transactionHash set to null. This indicates that your request has been accepted and the on-chain transfer process has started.
Once the transaction is broadcast, Interlace monitors its progress. The status will update to Closed after 30 block confirmations, and a valid transactionHash will be available.
You can use this transactionHash to track the transfer directly on-chain, for example via Etherscan's tracker on Sepolia.

Request Example

# Replace ${YOUR_API_ACCESS_TOKEN} with your API access token
curl --request POST \
     --url https://api-sandbox.interlace.money/open-api/v2/cryptoconnect/transfers \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-access-token: ${YOUR_API_ACCESS_TOKEN}' \
     --data '{
         "idempotencyKey": "bfafe401-a54d-445a-a6c5-4b407b68a2cc",
         "source": {
             "type": "cryptoconnect_wallet",
             "id": "785a98b0-057a-4a30-bbd2-40ea101f4d41"
         },
         "destination": {
             "type": "blockchain",
             "chain": "ETH",
             "address": "0x89F9Cfaa0dA076351DdfC6E320bD8df8b538dB17"
         },
         "amount": {
             "amount": "15",
             "currency": "USDC"
         }
     }'

Response Example

{
    "code": 0,
    "message": "ok",
    "data": {
        "id": "9008f61b-61dd-449b-bf97-d333290bf2b0",
        "idempotencyKey": "36408e88-0c3c-44bc-88c1-79cfa42b26d8",
        "accountId": "2aeafea5-0929-4bd4-91dc-fd1bbf4c101e",
        "source": {
            "type": "cryptoconnect_wallet",
            "id": "785a98b0-057a-4a30-bbd2-40ea101f4d41"
        },
        "destination": {
            "type": "blockchain",
            "chain": "ETH",
            "address": "0x89F9Cfaa0dA076351DdfC6E320bD8df8b538dB17",
            "format": "External Wallet"
        },
        "amount": {
            "amount": "15",
            "currency": "USDC"
        },
        "fees": [
            {
                "amount": "9",
                "currency": "USDC",
                "type": "GAS"
            },
            {
                "amount": "0.05",
                "currency": "USDC",
                "type": "CROSS_CHAIN"
            }
        ],
        "status": "Pending",
        "createTime": "1758531205984",
        "updateTime": "1758531207201"
    }
}

🎉 Congratulations! The cryptocurrency transfer has been successfully completed using Interlace APIs.