Wallet & Swap Open API

1 Introduction

1.1 Overview

The DTC Wallet OpenAPI, a JSON RESTful web service API, is for third-party partners to integrate DTC Wallet solutions with their own business website or services.

This specification defines a set of interfaces and security standards.

1.2 Specification Titles

• Name: The JSON field name in the request or response.

• Type: The JSON type of the field.

  • String, Integer, Long, Decimal (a JSON number, not a string — see the note below), Boolean, Enum (an integer ID unless stated otherwise), Object, Array.

• Required:

  • M — Mandatory. Validated by the server.
  • C — Conditional. Mandatory only under the condition stated in the Description column.
  • O — Optional.

• Description: The meaning, allowed values, or format of the field.

NOTE (numeric fields): Every amount/balance/fee/rate field in this document (amount, balance, fee, rate, gasFee, transactionFee, sellAmount, buyAmount, etc.) is a JSON number, both in requests and responses — e.g. "amount": 1.25, never "amount": "1.25". All JSON samples in this document follow that rule.

1.3 Security Standards

• HTTPS: TLS 1.2, mandatory for every connection.
• Whitelist: Optional IP whitelist, configurable on the API Key Management page.
• OAuth 2.0: Request session management.
• Signature: Request integrity checking.

2 Quick Start

2.1 Disclaimer

Use of these APIs is subject to dtcpay's review and approval. dtcpay reserves the right, at its sole discretion, to approve, restrict, suspend, or revoke access at any time.

2.2 Before Integration

1. Request account registration on the DTC Wallet platform.
2. Log in with the username/password issued by the DTC team and go to the API Key Management page.
3. Click + Create to open the dialog, and choose Wallet / Card API (not Payments API — that's a separate credential for the Payment Open API).
4. Enter the Name and IP Whitelist, then submit.
5. The API Key, API Secret, and Sign Key are generated and shown once. Keep them safe before closing the dialog.
6. Request domain names — see Fetch Access Token below.

2.3 OAuth 2.0 Authentication

2.3.1 Usage

Fetch an access token first, then add Authorization: Bearer {access_token} to every other request.

If the token expires, re-fetch it, or use Fetch Access Token by Refresh Token.

NOTE: Only one access token can exist at a time per client_id. Cache it (e.g. in Redis) rather than fetching a fresh one per request.

2.3.2 Fetch Access Token

Host

• Sbx test environment: https://open-api.sbx.dtcpayment.net
• Production environment: https://open-api.dtcpay.com

Request Body Sample

curl -X "POST" "https://{host}/auth/v1/oauth2/token" \
     -H "Content-Type: multipart/form-data; charset=utf-8; boundary=__X_PAW_BOUNDARY__" \
     -F "client_id=xxx" \
     -F "client_secret=xxx" \
     -F "grant_type=client_credentials"

The client_id/client_secret are obtained via the web portal at https://business.dtcpay.com/login — navigate to the API menu and create a Wallet / Card API to generate the credentials.

Response Body Sample

{
  "access_token": "CkppLkyiqEUKITGdtCZRUZBl",
  "expires_in": 21600,
  "refresh_token": "CpCAhcCRtLU4kPjs54omWW3A",
  "rt_expires_in": 43200,
  "token_type": "bearer"
}

NOTE: Access denied (errCode 00006) usually means a client_id/client_secret mismatch, or the calling IP does not match the whitelist configured for the API key.

2.3.3 Fetch Access Token by Refresh Token

Request Body Sample

curl -X "POST" "https://{host}/auth/v1/oauth2/token" \
     -H "Content-Type: multipart/form-data; charset=utf-8; boundary=__X_PAW_BOUNDARY__" \
     -F "refresh_token=CpCAhcCRtLU4kPjs54omWW3A" \
     -F "grant_type=refresh_token"

Response Body Sample — same shape as Fetch Access Token, with fresh access_token/refresh_token.

2.4 Request Signature

For every request, a signature is mandatory in the HTTP header — this is enforced unconditionally for every CLIENT-token-authenticated call (WalletOauthInterceptor.checkSignature), not just a "sensitive" subset.

1. Components of the string to sign:

   • HTTP Method — uppercase.
   • Timestamp — Timestamp number in millis, Singapore timezone. The request will be failed if the timestamp is before or after 2 minutes.
   • URL — the request path, no scheme/host.
   • Querystring — in-URL parameters without the leading ?, un-encoded.
   • Request Body — the exact raw body string, empty if none. Must match byte-for-byte, including invisible characters.

2. Concatenate in order: Method + Timestamp + URL + ('?' + Querystring if present) + Body.

GET1636360576641/wallet/v1/otc/reference-number/REF123?
POST1636360661729/wallet/v1/otc/get-otc-rate{"query":{"buyCurrency":"USD","sellCurrency":"USDC"}}

1. Sign the string with HMAC-SHA512 using the Sign Key from Before Integration, then Base64-encode the result.

2. Attach headers to the request:

   • D-TIMESTAMP — Timestamp number in millis, Singapore timezone. The request will be failed if the timestamp is before or after 2 minutes.
   • D-SIGNATURE — the generated signature.
   • D-SUB-ACCOUNT-ID — the id of sub account, registered under the master account. If a user has not been created through the dtc ekyc open API, this parameter does not need to be passed. This parameter can be understood as the client ID you want to operate on.
   • DTC-MFA-Data — only required by specific endpoints noted per-endpoint below (currently /wallet/v1/crypto-txn/withdraw and /wallet/v1/fiat-txn/withdraw, and only when the caller is an institution with sub-account MFA enabled).

NOTE: The server reads the raw body directly from the HTTP request stream for signature verification. The body used to compute the signature must be byte-identical to the body actually sent — any difference (an extra space, a different key order after re-serialization) breaks verification. Sign the exact same string you send, don't re-serialize a JSON object.

2.4.1 Example: GET Request (Java)

import com.google.common.hash.Hashing;
import java.nio.charset.StandardCharsets;
import java.util.Base64;

public class SignatureTestGuava {
    public static void main(String[] args) {
        String signKey = "4mt0MUecOtOEDI42WjN4BmM0";
        String method = "GET";
        String uri = "/wallet/v1/otc/reference-number/REF20250901001";
        String query = "";
        String body = "";
        String timestamp = String.valueOf(System.currentTimeMillis());

        String stringToSign = method + timestamp + uri;
        if (!query.isEmpty()) {
            stringToSign += "?" + query;
        }
        stringToSign += body;

        String signature = Base64.getEncoder().encodeToString(
                Hashing.hmacSha512(signKey.getBytes(StandardCharsets.UTF_8))
                        .hashBytes(stringToSign.getBytes(StandardCharsets.UTF_8))
                        .asBytes()
        );

        System.out.println("Timestamp   : " + timestamp);
        System.out.println("StringToSign: " + stringToSign);
        System.out.println("Signature   : " + signature);
    }
}

2.4.2 Example: POST Request (Java)

import com.google.common.hash.Hashing;
import java.nio.charset.StandardCharsets;
import java.util.Base64;

public class SignatureTestGuavaPOST {
    public static void main(String[] args) {
        String signKey = "4mt0MUecOtOEDI42WjN4BmM0";
        String method = "POST";
        String uri = "/wallet/v1/otc/get-otc-rate";
        String query = "";
        String body = "{\"query\":{\"buyCurrency\":\"USD\",\"sellCurrency\":\"USDC\"}}";
        String timestamp = String.valueOf(System.currentTimeMillis());

        String stringToSign = method + timestamp + uri;
        if (!query.isEmpty()) {
            stringToSign += "?" + query;
        }
        stringToSign += body;

        String signature = Base64.getEncoder().encodeToString(
                Hashing.hmacSha512(signKey.getBytes(StandardCharsets.UTF_8))
                        .hashBytes(stringToSign.getBytes(StandardCharsets.UTF_8))
                        .asBytes()
        );

        System.out.println("Timestamp    : " + timestamp);   // Value for D-TIMESTAMP
        System.out.println("StringToSign : " + stringToSign);
        System.out.println("Signature    : " + signature);   // Value for D-SIGNATURE
    }
}

3 API

3.1 Message Structure

Every request body:

{
  "query": {}
}

Paginated requests additionally carry:

{
  "query": {},
  "page": {
    "current": 1,
    "size": 10
  }
}

Responses come in three shapes depending on the endpoint:

Single object

{
  "header": {
    "success": true,
    "errCode": null,
    "errMsg": null
  },
  "result": {}
}

Plain list (no pagination — used by a small number of endpoints not covered in this document)

{
  "header": {
    "success": true
  },
  "resultList": []
}

Paginated list

{
  "header": {
    "success": true
  },
  "resultList": [],
  "pagination": {
    "current": 1,
    "size": 10,
    "total": 100
  }
}

Failure:

{
  "header": {
    "success": false,
    "errCode": "31005",
    "errMsg": "Card Information is invalid"
  }
}

3.2 Wallet Account

3.2.1 Get Balance

Endpoint

[GET] /wallet/v1/account/balance/{currency}

Description

Retrieve the balance for a specific currency wallet owned by the caller.

Path Variables

Response Parameters

Response Body Sample

{
  "header": {
    "success": true
  },
  "result": {
    "balance": 10.12
  }
}

Possible Error Codes

3.2.2 Get All Wallet Balances

Endpoint

[GET] /wallet/v1/account/balances

Description

Retrieve all of the caller's wallet account balances, one row per currency the caller has a wallet account for.

Response Parameters (array of wallet accounts in resultList)

Response Body Sample

{
  "header": {
    "success": true
  },
  "resultList": [
    {
      "id": 988,
      "clientId": 8520111007,
      "currency": "HKD",
      "balance": 70526.27,
      "updatedAt": "2026-09-02 16:13:59"
    },
    {
      "id": 987,
      "clientId": 8520111007,
      "currency": "EUR",
      "balance": 544.39,
      "updatedAt": "2026-09-02 16:13:59"
    }
  ]
}

Possible Error Codes

3.2.3 Wallet Transfer

Endpoint

[POST] /wallet/v1/account/transfer

Description

Transfer funds from the caller's own wallet of currency to another dtcpay client's wallet of the same currency, identified by recipientClientId. There is no currency conversion — the recipient's wallet of that same currency is credited the exact amount debited. This is a pure internal ledger move between two dtcpay-hosted wallets; it never touches a blockchain or a third-party bank, regardless of whether currency is fiat or stablecoin.

Contrast with Business Transfer below: transfer supports any currency the caller has a wallet for, needs no supporting documents, and has no receiver-eligibility whitelist gate. business-transfer is stablecoin-only by default (fiat only for whitelisted callers), requires supporting document fileIds, and additionally accepts a recipientDtcpayTag identifier.

Request Parameters

Request Body Sample

{
  "query": {
    "currency": "SGD",
    "amount": 1.25,
    "recipientClientId": 85250630150001070,
    "note": "test1"
  }
}

Response Parameters

A wallet transfer always creates two transaction rows — a TRANSFER_OUT leg on the caller's own wallet and a TRANSFER_IN leg on the recipient's wallet — both of which are their own Inquiry Wallet Balance History row (relatedId = that leg's own transaction id), so both are returned.

Exactly one pair (fiatTransferOut+fiatTransferIn, or cryptoTransferOut+cryptoTransferIn) is populated, matching whether currency was fiat or stablecoin.

Response Body Sample — fiat

{
  "header": {
    "success": true
  },
  "result": {
    "fiatTransferOut": {
      "id": 2510202055340218000,
      "clientId": 250507120005941,
      "type": 6,
      "state": 200,
      "currency": "SGD",
      "amount": 1,
      "transactionFee": 0,
      "senderAccountId": 250507120005941,
      "recipientAccountId": 85250630150001070,
      "recipientAmount": 1,
      "referenceNo": "20260428153012345A7K3X9",
      "operator": "[250507120005941] test1",
      "approver": "[250507120005941] test1",
      "createdAt": "2026-09-02 16:13:59",
      "completedAt": "2026-09-02 16:13:59",
      "updatedAt": "2026-09-02 16:13:59"
    },
    "fiatTransferIn": {
      "id": 2510202055340219000,
      "clientId": 85250630150001070,
      "type": 5,
      "state": 200,
      "currency": "SGD",
      "amount": 1,
      "transactionFee": 0,
      "senderAccountId": 250507120005941,
      "recipientAccountId": 85250630150001070,
      "recipientAmount": 1,
      "referenceNo": null,
      "operator": "[250507120005941] test1",
      "approver": null,
      "createdAt": "2026-09-02 16:13:59",
      "completedAt": "2026-09-02 16:13:59",
      "updatedAt": "2026-09-02 16:13:59"
    }
  }
}

Response Body Sample — stablecoin

{
  "header": {
    "success": true
  },
  "result": {
    "cryptoTransferOut": {
      "id": 2510202054090305000,
      "type": 7,
      "state": 200,
      "clientId": 250507120005941,
      "mainNet": null,
      "amount": 1,
      "currency": "USDC",
      "transactionFee": 0,
      "gasFee": 0,
      "recipientAddressId": 85250630150001070,
      "recipientAddress": null,
      "senderAddressId": 250507120005941,
      "senderAddress": null,
      "referenceNo": "20260428153012345A7K3X9",
      "remark": "test",
      "operator": "[250507120005941] test1",
      "createdAt": "2026-09-02 16:13:59",
      "updatedAt": "2026-09-02 16:13:59"
    },
    "cryptoTransferIn": {
      "id": 2510202054090306000,
      "type": 6,
      "state": 200,
      "clientId": 85250630150001070,
      "mainNet": null,
      "amount": 1,
      "currency": "USDC",
      "transactionFee": 0,
      "gasFee": 0,
      "recipientAddressId": 85250630150001070,
      "recipientAddress": null,
      "senderAddressId": 250507120005941,
      "senderAddress": null,
      "referenceNo": null,
      "remark": "test",
      "operator": "[250507120005941] test1",
      "createdAt": "2026-09-02 16:13:59",
      "updatedAt": "2026-09-02 16:13:59"
    }
  }
}

mainNet/recipientAddress/senderAddress are null here because a wallet-transfer recipient is identified by recipientClientId, not by a whitelisted blockchain address — there is no address record to resolve.

Possible Error Codes

3.2.4 Business Transfer

Endpoint

[POST] /wallet/v1/account/business-transfer

Description

Transfer from the caller's own wallet of currency to a recipient identified by either recipientClientId or recipientDtcpayTag (exactly one must be set), with mandatory supporting document fileIds.

By default, only stablecoin currencies are accepted. Fiat is additionally allowed only for callers enrolled in the fiat receiver-constraint beta whitelist (contact dtcpay to enroll); for those callers, a receiver-eligibility check (KYC tier / balance cap) also runs against the recipient when identified by recipientClientId. A recipientDtcpayTag that resolves to an individual (not a business) is always rejected — dtag-addressed business transfers are B2B only.

Request Parameters

Request Body Sample — by client ID

{
  "query": {
    "currency": "USDC",
    "amount": 100.0,
    "recipientClientId": 260318130073305,
    "fileIds": [
      998001,
      998002
    ],
    "note": "April KOL commission"
  }
}

Request Body Sample — by dtcpay tag

{
  "query": {
    "currency": "USDC",
    "amount": 100.0,
    "recipientDtcpayTag": "@kolalice",
    "fileIds": [
      998001
    ],
    "note": "April KOL commission"
  }
}

Response Parameters

Same two-leg shape as Wallet Transfer — a business transfer creates a TRANSFER_OUT leg on the caller's own wallet and a TRANSFER_IN leg on the recipient's wallet, each its own Inquiry Wallet Balance History row, so both are returned.

Response Body Sample — fiat (whitelisted callers only)

{
  "header": {
    "success": true
  },
  "result": {
    "fiatTransferOut": {
      "id": 2606031457480355794,
      "clientId": 8522120036,
      "type": 6,
      "state": 200,
      "currency": "SGD",
      "amount": 100.0,
      "transactionFee": 0,
      "senderAccountId": 8522120036,
      "recipientAccountId": 260318130073305,
      "recipientAmount": 100.0,
      "referenceNo": "20260603145748abc123",
      "operator": "[8522120036] test",
      "approver": "[8522120036] test",
      "createdAt": "2026-06-03 14:57:48",
      "completedAt": "2026-06-03 14:57:48",
      "updatedAt": "2026-06-03 14:57:48"
    },
    "fiatTransferIn": {
      "id": 2606031457480355795,
      "clientId": 260318130073305,
      "type": 5,
      "state": 200,
      "currency": "SGD",
      "amount": 100.0,
      "transactionFee": 0,
      "senderAccountId": 8522120036,
      "recipientAccountId": 260318130073305,
      "recipientAmount": 100.0,
      "referenceNo": null,
      "operator": "[8522120036] test",
      "approver": null,
      "createdAt": "2026-06-03 14:57:48",
      "completedAt": "2026-06-03 14:57:48",
      "updatedAt": "2026-06-03 14:57:48"
    }
  }
}

Response Body Sample — stablecoin

{
  "header": {
    "success": true
  },
  "result": {
    "cryptoTransferOut": {
      "id": 2606031457480355796,
      "type": 7,
      "state": 200,
      "clientId": 8522120036,
      "amount": 100.0,
      "currency": "USDC",
      "gasFee": 0,
      "transactionFee": 0,
      "recipientAddressId": 260318130073305,
      "recipientAddress": null,
      "senderAddressId": 8522120036,
      "senderAddress": null,
      "referenceNo": "20260603145748abc123",
      "operator": "[8522120036] test",
      "createdAt": "2026-06-03 14:57:48",
      "updatedAt": "2026-06-03 14:57:48"
    },
    "cryptoTransferIn": {
      "id": 2606031457480355797,
      "type": 6,
      "state": 200,
      "clientId": 260318130073305,
      "amount": 100.0,
      "currency": "USDC",
      "gasFee": 0,
      "transactionFee": 0,
      "recipientAddressId": 260318130073305,
      "recipientAddress": null,
      "senderAddressId": 8522120036,
      "senderAddress": null,
      "referenceNo": null,
      "operator": "[8522120036] test",
      "createdAt": "2026-06-03 14:57:48",
      "updatedAt": "2026-06-03 14:57:48"
    }
  }
}

Possible Error Codes

3.2.5 Inquiry Wallet Balance History

Endpoint

[POST] /wallet/v1/account/balance/history/inquiry

Description

Paginated read of the caller's own rows in wallet.wallet_balance_history — one row per ledger entry that changed a wallet's balance. This is a plain range/equality query against that table, not a merged view across other business objects: relatedId is returned as-is and its meaning depends on type (e.g. for type=FIAT_WITHDRAWAL it is a FiatTransaction ID, for type=CRYPTO_DEPOSIT a CryptoTransaction ID, for type=OTC an Otc ID — see Enum List — ActivityType for the full mapping). To see the details of a specific activity, look it up through the corresponding endpoint (e.g. GET /wallet/v1/fiat-txn/{txnId}) using relatedId together with type.

Request Parameters

Request Body Sample

{
  "query": {
    "currency": "USDC"
  },
  "page": {
    "current": 1,
    "size": 10
  }
}

Response Parameters

Response Body Sample

{
  "header": {
    "success": true
  },
  "resultList": [
    {
      "id": 2509231015230507618,
      "walletAccountId": 988,
      "currency": "USDC",
      "type": 15,
      "relatedId": 240501000012345,
      "balanceBefore": 68304.05,
      "changeAmount": 2222,
      "balanceAfter": 70526.05,
      "completedAt": "2025-09-23 10:15:24",
      "updatedAt": "2025-09-23 10:15:24"
    }
  ],
  "pagination": {
    "current": 1,
    "size": 10,
    "total": 1980
  }
}

Possible Error Codes

This endpoint has no dedicated failure path beyond the common 00006 Access denied (missing authClient — returns an empty resultList, not an error header) — any other failure is a 500 from an unexpected exception.

3.3 OTC (Swap)

3.3.1 Sequence Diagram

Sequence diagram: see the interactive version in the dtcpay developer portal (PDF export available on request).

3.3.2 Get OTC Order

Endpoint

[GET] /wallet/v1/otc/{otcId}

Description

Retrieve an OTC (swap) order by ID. Returns the same object shape as Inquiry OTC Orders / Get OTC Order by Reference Number / Request OTC.

Path Variables

Response Parameters

Response Body Sample

{
  "header": {
    "success": true
  },
  "result": {
    "id": 2510101421380624067,
    "status": 5,
    "clientId": 8524010424,
    "sellCurrency": "GBP",
    "buyCurrency": "USD",
    "rate": 1.345119262388,
    "dtcQuoteId": 1155389391925733471,
    "sellAmount": 0.75,
    "buyAmount": 1,
    "operator": "[8524010424] openapi",
    "referenceNo": "173561238951",
    "completedAt": "2025-10-10 14:21:39",
    "updatedAt": "2025-10-10 14:21:39"
  }
}

Possible Error Codes

3.3.3 Inquiry OTC Orders

Endpoint

[POST] /wallet/v1/otc/inquiry

Description

Look up the caller's OTC orders by pagination. Same response object shape as Get OTC Order.

Request Parameters

Request Body Sample

{
  "query": {
    "status": 5,
    "buyCurrency": "USDC",
    "sellCurrency": "USD",
    "createTimeFrom": "2026-01-01 00:00:00",
    "createTimeTo": "2026-01-31 23:59:59"
  },
  "page": {
    "current": 1,
    "size": 50
  }
}

Response Body Sample — array of the same object as Get OTC Order:

{
  "header": {
    "success": true
  },
  "resultList": [
    {
      "id": 2508071556490618367,
      "status": 5,
      "clientId": 8524010424,
      "sellCurrency": "SGD",
      "buyCurrency": "USDC",
      "rate": 0.7702672119830299,
      "dtcQuoteId": 1155389391900000000,
      "sellAmount": 123123,
      "buyAmount": 94837.6,
      "referenceNo": "xsdf34234324",
      "operator": "downey.wang@dtc.top",
      "completedAt": "2025-08-07 15:56:50",
      "updatedAt": "2025-08-07 15:56:50"
    }
  ],
  "pagination": {
    "current": 1,
    "size": 50,
    "total": 1
  }
}

Possible Error Codes

3.3.4 Get OTC Order by Reference Number

Endpoint

[GET] /wallet/v1/otc/reference-number/{referenceNo}

Description

Retrieve an OTC order by reference number. Same object shape as Get OTC Order / Inquiry OTC Orders / Request OTC.

Path Variables

Response Body Sample — same shape as Get OTC Order.

Possible Error Codes

3.3.5 Get OTC Rate

Endpoint

[POST] /wallet/v1/otc/get-otc-rate

Description

Get a locked exchange rate quote for an OTC swap.

Request Parameters

At least one of sellAmount/buyAmount must be provided; if both are omitted, only indicative rate information is returned.

Request Body Sample

{
  "query": {
    "buyCurrency": "USD",
    "sellCurrency": "GBP"
  }
}

Response Parameters

How long is the quote valid for? rate/sellAmount/buyAmount are only guaranteed until expiresAt:

• Fiat↔stablecoin pairs (a USD-pegged fiat currency against a stablecoin): 7 days.
• Every other pair (the default for a standard OTC enquiry): 24 hours.

Call this endpoint again to get a fresh rate once expired; a dtcQuoteId can only be consumed once regardless.

Response Body Sample

{
  "header": {
    "success": true
  },
  "result": {
    "sellCurrency": "GBP",
    "buyCurrency": "USD",
    "clientId": 8524010424,
    "expiresAt": "2025-10-10 14:22:15",
    "rate": 1.345119262388,
    "quoteId": 1155389391925733471,
    "balance": 10.79,
    "sellWalletBalance": 10.79,
    "buyWalletBalance": 4725.06
  }
}

Possible Error Codes

3.3.6 Request OTC

Endpoint

[POST] /wallet/v1/otc/request

Description

Submit an OTC swap using a quote obtained from Get OTC Rate. Same response object shape as Get OTC Order / Inquiry OTC Orders / Get OTC Order by Reference Number.

Request Parameters

Request Body Sample

{
  "query": {
    "buyCurrency": "USD",
    "buyAmount": 1,
    "sellCurrency": "GBP",
    "sellAmount": 0.75,
    "dtcQuoteId": 1155389391925733471,
    "referenceNo": "173561238951"
  }
}

Response Body Sample — same shape as Get OTC Order.

Possible Error Codes

3.4 RAA (Risk Awareness Assessment)

MAS requires every DPT (Digital Payment Token) user to pass a Risk Awareness Assessment before their first stablecoin deposit. RAA lets a partner present DTC's risk assessment inside its own user journey instead of redirecting to a DTC-hosted page: the partner retrieves the question bank (including the answer key), presents questionsToDraw questions, grades the attempt itself, and calls dtcpay only once the user has met answersNeededCorrect — dtcpay re-grades the submission against its own key rather than trusting the caller's result.

NOTE

• Use questionsToDraw to decide how many questions to present and answersNeededCorrect to decide whether the user has passed — do not hard-code either number, the bank can be resized or the pass bar moved independently of this document.
• Submit the complete set of answers (including any wrong one) only after the user has met answersNeededCorrect. A submission that falls short of the bar is rejected and the account is placed under manual review (50021), it is not silently marked as failed and re-triable.
• Only raaStatus = 2 (COMPLETED) is a pass. If Query RAA Status is unavailable or errors, treat the user as PENDING (1) and withhold the gated action — never fail open.
• If you plan to enable crypto stablecoin deposits for a client, RAA must be completed for that client first — see the note at the top of Crypto (Stablecoin) below.

3.4.1 Sequence Diagram

Sequence diagram: see the interactive version in the dtcpay developer portal (PDF export available on request).

3.4.2 Get RAA Question Bank

Endpoint

[GET] /wallet/v1/raa/bank

Description

Returns every enabled RAA question for a locale, including the answer key — the caller presents the questions and grades the attempt itself. A locale with no questions seeded falls back to English; the language actually served is echoed back in locale so the caller renders text consistent with what it will later submit.

Query Parameters

Query Parameters Sample

GET /wallet/v1/raa/bank?assessmentCode=DPT_RISK_AWARENESS&locale=EN

Response Parameters

Response Body Sample — real question shown, remaining 93 questions omitted for brevity (see wallet-execution-report.md item 17 / transcripts/wallet/18_raa_bank.json for the full 94-question capture):

{
  "header": {
    "success": true
  },
  "result": {
    "assessmentCode": "DPT_RISK_AWARENESS",
    "totalQuestions": 94,
    "questionsToDraw": 5,
    "passCriteria": "MIN_CORRECT",
    "answersNeededCorrect": 4,
    "locale": "EN",
    "questions": [
      {
        "questionId": 3,
        "type": "SINGLE_CHOICE",
        "questionContent": "Which statement(s) is/are true about most digital payment tokens(DPTs) such as Bitcoin?",
        "options": [
          {
            "optionId": "A",
            "optionContent": "The prices of DPTs are stable and do not vary greatly over time."
          },
          {
            "optionId": "B",
            "optionContent": "Most DPTs have a minimum guaranteed value."
          },
          {
            "optionId": "C",
            "optionContent": "The prices of DPT can fluctuate greatly."
          },
          {
            "optionId": "D",
            "optionContent": "It is impossible for DPTs to lose all their value."
          }
        ],
        "correctOptionIds": [
          "B"
        ]
      }
      // ...remaining 93 questions omitted from this sample
    ]
  }
}

Possible Error Codes

3.4.3 Submit RAA Result

Endpoint

[POST] /wallet/v1/raa/submissions

Description

Call once the user has answered at least answersNeededCorrect of the presented questions correctly. Send every answer, including any that were wrong — the question and selected-answer text as displayed to the user must be included, compliance requires the record to preserve exactly what the user saw. Idempotent: replaying a submissionId, or submitting for a user who already completed, returns the original result with recorded = false rather than an error. dtcpay re-grades on the same rule as the question bank; an attempt short of the bar is rejected and routed to manual review rather than accepted or silently dropped. The sub-account the submission is recorded against is resolved the same way as every other endpoint in this document — from the authenticated caller (D-SUB-ACCOUNT-ID), not a body parameter.

Request Parameters

Request Body Sample

{
  "query": {
    "assessmentCode": "DPT_RISK_AWARENESS",
    "submissionId": "aix-20260911-7f3a9c1e",
    "completedAt": "2026-09-11T10:15:30+08:00",
    "locale": "EN",
    "answers": [
      {
        "questionId": 61,
        "selectedOptionIds": [
          "B"
        ]
      },
      {
        "questionId": 62,
        "selectedOptionIds": [
          "A"
        ]
      },
      {
        "questionId": 63,
        "selectedOptionIds": [
          "C"
        ]
      },
      {
        "questionId": 64,
        "selectedOptionIds": [
          "D"
        ]
      },
      {
        "questionId": 65,
        "selectedOptionIds": [
          "B"
        ]
      }
    ]
  }
}

Response Parameters

Response Body Sample

{
  "header": {
    "success": true
  },
  "result": {
    "submissionId": "aix-20260911-7f3a9c1e",
    "raaStatus": 2,
    "recorded": true,
    "completedAt": "2026-09-11 10:15:30"
  }
}

Possible Error Codes

3.4.4 Query RAA Status

Endpoint

[GET] /wallet/v1/raa/status

Description

Query a sub-account's current RAA status — the basis for deciding whether to prompt the assessment and for gating crypto deposits. If this endpoint is unavailable or errors, treat the user as PENDING and withhold the gated action; do not fail open.

Query Parameters

Response Parameters

Response Body Sample

{
  "header": {
    "success": true
  },
  "result": {
    "clientId": 250426220002035,
    "raaStatus": 2,
    "completedAt": "2026-09-11 10:15:30"
  }
}

Possible Error Codes

3.5 Crypto (Stablecoin)

Before enabling crypto stablecoin deposits for a client, that client must have completed RAA (Risk Awareness Assessment) (raaStatus = 2 / COMPLETED on Query RAA Status) — this is a MAS requirement, not a dtcpay-specific gate, and it applies before the first deposit rather than being enforced per-transaction after the fact.

3.5.1 Get Supported Networks By Address

Endpoint

[GET] /wallet/v1/crypto/address/network/{address}

Description

Given a wallet address string, detect which of dtcpay's currently-enabled blockchain networks (MainNet) it is a valid format for. Useful when a partner has collected a recipient's raw address and needs to know which mainnet(s) to associate it with before whitelisting it. Detection is purely address-format validation (regex/checksum), not an on-chain existence check — and an EVM-style address (0x + 40 hex chars) matches every EVM-compatible network at once (see Enum List — MainNet), since that address format is chain-agnostic. BITCOIN is never returned by this endpoint (no Bitcoin address format check is implemented here). Matches are further filtered down to only the networks currently marked visible in dtcpay's network configuration — a recognized address format can still be filtered out if that network isn't currently enabled for partners.

Path Variables

Response Parameters

Response Body Sample

{
  "header": {
    "success": true
  },
  "result": {
    "supportMainNetList": [
      2,
      3,
      7,
      8,
      10
    ]
  }
}

Possible Error Codes

3.5.2 Get Supported Currencies By MainNet

Endpoint

[GET] /wallet/v1/crypto/address/currency/{mainNet}

Description

List the currencies dtcpay currently supports depositing/withdrawing on a given blockchain network (MainNet), ordered by the platform's configured display order. Useful for building a currency picker once a network has already been chosen (e.g. right after Get Supported Networks By Address). An unrecognized mainNet ID, or a recognized network with no currently-visible currencies configured, both return an empty supportCurrencyList rather than an error.

Path Variables

Response Parameters

Response Body Sample

{
  "header": {
    "success": true
  },
  "result": {
    "supportCurrencyList": [
      "USDC",
      "USDC",
      "WUSD"
    ]
  }
}

Possible Error Codes

3.5.3 Sequence Diagram (Deposit)

Sequence diagram: see the interactive version in the dtcpay developer portal (PDF export available on request).

Most deposit-address / whitelist-address management endpoints (whitelist/deposit-target lookup, add-client-own, etc.) are out of scope for this document. The two network/currency lookup endpoints (Get Supported Networks By Address / Get Supported Currencies By MainNet) are the one exception and are documented here.

Whitelist and Risk Withheld: a deposit involves a senderAddress (the address funds are sent from) and the destinationAddress DTC assigns to the client as its deposit target (returned by the deposit-target lookup endpoint noted above). Before depositing, the client's senderAddress must be added to the whitelist and enabled — this is managed on the web platform (API Key Management), not by an open API endpoint. If a deposit arrives from a senderAddress that is not on the whitelist, the transaction is created with state = RISK_WITHHELD (102) instead of completing — it is held pending review, not rejected. Once the client adds the same senderAddress to the whitelist and enables it, the held transaction automatically transitions to its normal completed state; no separate retry or resubmission is needed.

如何在 stg 测试环境充值（testnet）：目前测试环境仅支持以太坊（Sepolia 测试网）+ USDC 币种，具体流程如下：

1. 在 MetaMask 插件中创建一个钱包;
2. 在 MetaMask 中添加 Sepolia USDC 代币，合约地址：0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238;
3. 通过 https://faucet.circle.com/ 往刚创建的钱包地址领取测试币，大概几分钟后该钱包地址将收到款项;
4. 用该钱包地址作为 senderAddress，调用 Add Client Own Address (POST /wallet/v1/crypto/address/add-client-own) 添加白名单，再调用 (POST /wallet/v1/crypto/address/set-enabled) 启用；
5. 在 MetaMask 中选择对应的 USDC 代币，往 dtcpay 分配的充值目标地址（destinationAddress，见上方 deposit-target lookup 接口）转账，即可触发充值流程。

3.5.4 Sequence Diagram (Withdraw)

Users withdraw to a whitelisted address only. A withdraw request returning success means the request was accepted, not that on-chain settlement has completed — poll by ID/hash/referenceNo, or listen for the webhook.

Sequence diagram: see the interactive version in the dtcpay developer portal (PDF export available on request).

3.5.5 Inquiry Crypto Transactions

Endpoint

[POST] /wallet/v1/crypto-txn/inquiry

Description

Paginated, filterable lookup of the caller's crypto transactions, ordered by ID descending (latest first). Each row includes the resolved sender/recipient blockchain addresses (recipientAddress/senderAddress, resolved server-side from the whitelist by recipientAddressId/senderAddressId) plus gasFee and transactionFee. Returns the same object shape as Get Crypto Transaction / Get Crypto Transaction by Reference Number / Get Crypto Transaction by txnHash — one unified CryptoTransactionResp used by all four query paths.

Request Parameters

Request Body Sample

{
  "query": {
    "type": 1,
    "mainNet": 3,
    "currency": "USDC",
    "senderAddressId": 2233,
    "transactionDateFrom": "2026-09-01 00:00:00",
    "transactionDateTo": "2026-09-30 23:59:59"
  },
  "page": {
    "current": 1,
    "size": 10
  }
}

Response Parameters — (this shape is shared by inquiry / get-by-id / get-by-hash / get-by-reference-number; clientId is always scrubbed to null on the inquiry result specifically):

Response Body Sample

{
  "header": {
    "success": true
  },
  "resultList": [
    {
      "id": 2508261801180309870,
      "type": 1,
      "state": 200,
      "clientId": null,
      "mainNet": 3,
      "amount": 1.0,
      "currency": "USDC",
      "transactionFee": 30.0,
      "txnHash": "0x05207c3f87c77ffbf0e038d1667794d1fde8f0081ad118f8c4a01673f4a88fe1",
      "referenceNo": "REF20250901001",
      "remark": "User deposit",
      "createdAt": "2025-08-26 18:01:18",
      "updatedAt": "2025-08-26 18:01:18",
      "gasFee": 0,
      "operator": null,
      "recipientAddressId": 2851,
      "recipientAddress": "0x39c929CCB23116e39aE1297B0157F38ecf501D6a",
      "senderAddressId": 2233,
      "senderAddress": "0x73868CA4bdeEe665FEF2d62C25D64bfD58B63327"
    }
  ],
  "pagination": {
    "current": 1,
    "size": 10,
    "total": 2
  }
}

Possible Error Codes

3.5.6 Get Crypto Transaction Withdraw Fee

Endpoint

[POST] /wallet/v1/crypto-txn/withdraw-fee

Description

Get the fee estimate for a crypto withdrawal.

Request Parameters

Request Body Sample

{
  "query": {
    "amount": 0.01,
    "currency": "USDC"
  }
}

Response Parameters

Response Body Sample

{
  "header": {
    "success": true
  },
  "result": {
    "fee": 7.0
  }
}

Possible Error Codes

3.5.7 Crypto Withdraw

Endpoint

[POST] /wallet/v1/crypto-txn/withdraw

Description

Withdraw stablecoin from the caller's wallet to a whitelisted external address. Returns a create-style acknowledgement (not the full transaction object — poll Get Crypto Transaction for the final state).

A successful call only means the withdrawal request was accepted, not that funds have moved. Every crypto withdrawal must clear an internal approval step before it settles on-chain; this has a turnaround time and does not complete immediately. The returned state always starts at PENDING (or RISK_WITHHELD if the recipient address fails a whitelist/risk check — see Sequence Diagram (Deposit) above for the equivalent deposit-side behavior). Poll Get Crypto Transaction by cryptoTransactionId, or listen for the CRYPTO_TXN webhook, to learn when it actually settles.

DTC-MFA-Data header: required when the caller is an institution with sub-account MFA enabled (see Request Signature); enforced identically to the legacy /openapi/v1/crypto-txn/withdraw endpoint — both the requirement-gating interceptor (openApiMfaInterceptor) and the service-layer check that the supplied token corresponds to a genuinely completed face-auth session (OpenApiMfaService.isSubAccountAuthTokenValid, same call legacy makes) are wired identically.

Request Parameters

Request Body Sample

{
  "query": {
    "recipientAddressId": 516,
    "amount": 10,
    "currency": "USDC",
    "referenceNo": "REF20260901001"
  }
}

Response Parameters

Response Body Sample

{
  "header": {
    "success": true
  },
  "result": {
    "cryptoTransactionId": 2508261801180309870,
    "state": 0
  }
}

Possible Error Codes

3.5.8 Get Crypto Transaction

Endpoint

[GET] /wallet/v1/crypto-txn/{txnId}

Description

Get crypto transaction details by transaction ID. Same object shape as Inquiry Crypto Transactions / Get Crypto Transaction by Reference Number / Get Crypto Transaction by txnHash — clientId is populated (not scrubbed) on this path.

Path Variables

Response Body Sample — same fields as Inquiry Crypto Transactions:

{
  "header": {
    "success": true
  },
  "result": {
    "id": 2604081724300340700,
    "type": 2,
    "state": 101,
    "clientId": 8522120036,
    "mainNet": 3,
    "amount": 200,
    "currency": "USDC",
    "transactionFee": 114.22,
    "gasFee": 0,
    "txnHash": null,
    "referenceNo": null,
    "remark": null,
    "operator": "evelyn.kong@dtcpay.com",
    "recipientAddressId": 63911479,
    "recipientAddress": "0x29451adE1244Ce8F6E6fBA87E7A27c06dbc07249",
    "senderAddressId": null,
    "senderAddress": null,
    "createdAt": "2026-04-08 17:24:30",
    "updatedAt": "2026-04-08 17:24:31"
  }
}

Possible Error Codes

3.5.9 Get Crypto Transaction by Reference Number

Endpoint

[GET] /wallet/v1/crypto-txn/reference-number/{referenceNo}

Same object shape and error handling pattern as Get Crypto Transaction. referenceNo is a path variable.

Possible Error Codes

3.5.10 Get Crypto Transaction by txnHash

Endpoint

[GET] /wallet/v1/crypto-txn/txnhash/{txnHash}

Same object shape as Get Crypto Transaction. txnHash is a path variable.

Possible Error Codes

3.6 Fiat

3.6.1 Sequence Diagram (Deposit)

Sequence diagram: see the interactive version in the dtcpay developer portal (PDF export available on request).

3.6.2 Sequence Diagram (Withdraw)

Sequence diagram: see the interactive version in the dtcpay developer portal (PDF export available on request).

3.6.3 Get Fiat Transaction

Endpoint

[GET] /wallet/v1/fiat-txn/{txnId}

Description

Get fiat transaction details by transaction ID. Same object shape as Inquiry Fiat Transactions / Fiat Withdraw / Fiat Deposit / Get Fiat Transaction by Reference Number — one unified FiatTransactionResp used by all five paths.

Path Variables

Response Parameters

Response Body Sample

{
  "header": {
    "success": true
  },
  "result": {
    "id": 2604081409370246000,
    "clientId": 8522120036,
    "type": 8,
    "state": 101,
    "currency": "SGD",
    "amount": 23,
    "transactionFee": 0,
    "senderAccountId": 489,
    "recipientAccountId": 11957,
    "recipientAmount": 23,
    "referenceNo": null,
    "operator": null,
    "approver": null,
    "createdAt": "2026-04-08 14:09:37",
    "updatedAt": "2026-04-08 14:09:38"
  }
}

Possible Error Codes

3.6.4 Inquiry Fiat Transactions

Endpoint

[POST] /wallet/v1/fiat-txn/inquiry

Same response object shape as Get Fiat Transaction.

Request Parameters

Request Body Sample

{
  "query": {
    "state": 101,
    "type": 1,
    "currency": "USD",
    "createTimeFrom": "2026-01-01",
    "createTimeTo": "2026-01-31"
  },
  "page": {
    "current": 1,
    "size": 20
  }
}

Response Body Sample — array of the object in Get Fiat Transaction:

{
  "header": {
    "success": true
  },
  "resultList": [
    {
      "id": 2604081409370246000,
      "clientId": 8522120036,
      "type": 8,
      "state": 101,
      "currency": "SGD",
      "amount": 23,
      "transactionFee": 0,
      "senderAccountId": 489,
      "recipientAccountId": 11957,
      "operator": "evelyn.kong@dtcpay.com",
      "approver": "evelyn.kong@dtcpay.com",
      "purpose": 99,
      "createdAt": "2026-04-08 14:09:37",
      "updatedAt": "2026-04-08 14:09:38"
    }
  ],
  "pagination": {
    "current": 1,
    "size": 20,
    "total": 2006
  }
}

Possible Error Codes

3.6.5 Get Fiat Withdrawal Fee

Endpoint

[POST] /wallet/v1/fiat-txn/withdraw-fee

Description

Calculate the applicable fee for a fiat withdrawal to a specific recipient bank account.

Request Parameters

Request Body Sample

{
  "query": {
    "recipientRemitInfoId": 12,
    "amount": 1.35
  }
}

Response Parameters