Dabank

Dabank is a commercial cloud-based white-labeled cryptocurrency wallet service, supporting a wide range of coins.

With Dabank API, you are able to provide your customers with deposit, vault and withdrawal with grace and speed.

General

Communication

You ("app") and Dabank communicate in a bi-directional way:

You call APIs to apply for deposit address, trigger a withdrawal, etc
Dabank calls back to you for transaction status update, like new deposit arrival, deposit confirmation, withdrawal confirmation, etc

Data Type

Data of input and output only consists of following basic type:

string - most data type in use (mind all numbers(int/float) are represented in string format)

Array and Object are used on top of basic type.

Request

All APIs uses HTTP POST method, with Content-Typeheader application/json; charset=utf-8.

Authentication

SHA256-RSA Authentication

For every API following, these inputs are needed in request for authentication:

key	type	comment
key	string	key provides identity
sign	string	SHA256-RSA data signature
request_time	string	current unix second

keys

There are two sets of key-pair involved in SHA256-RSA Authentication:

You use app_private_key(kept as secret) to sign your API requests, and you upload app_public_key to Dabank for request verification;
You download dabank_public_key for callback verification, as Dabank uses dabank_private_key to sign callbacks.

Generation of app_private_key and app_public_key

You may use OpenSSL to generate RSA key pairs, note the key length is 2048.

openssl genrsa -out app_private_key.pem 2048
openssl rsa -in app_private_key.pem -pubout -out app_public_key.pem

Steps to generate sign(for API requests)

sign is generated in following steps:

extract all keys and values in JSON's key-value pair(except sign) in the form of key=value, as array param;
sort param in lexical order;
join param with & to obtain string content;
calculate sha256 of content to get hashed;
calculate the signature of hashed with app_private_key using RSASSA-PKCS1-V1_5-SIGN from RSA PKCS#1 v1.5 to get rsa_sign;
encode rsa_sign with base64 and you get sign of your current request.

Steps to verify sign(for Dabank callback verification)

extract all keys and values in JSON's key-value pair(except sign) in the form of key=value, as array param;
sort param in lexical order;
join param with & to obtain string content;
calculate sha256 of content to get hashed;
verify the signature of hashed with dabank_public_key using RSASSA-PKCS1-V1_5-VERIFY from RSA PKCS#1 v1.5

HMAC-style Authentication(Deprecated)

HMAC-style Authentication is deprecated, which will be dropped in future.

For every API following, these inputs are needed in request for authentication:

key	type	comment
key	string	key provides identity
sign	string	HMAC-style data signature
request_time	string	current unix second

Steps to generate sign(for API requests and Dabank callback verification)

sign is generated in following steps:

extract all values except sign in JSON's key-value pair to array values;
put your secret(obtained from control panel of Dabank) into values;
sort values in lexical order;
join values with underline _ to obtain string content;
calculate md5 of content and you get sign of your current request.

Documentations on above-mentioned authentication input are omitted from now on for brevity.

Response

All responses are boxed in following object:

key	type	comment
err_code	string	code of error, empty when everything is fine
err_info	string	description for error
request_id	int	id for request booking, 0 if it is not booked
data	object/array	output of API

Example:

{ 
    "err_code": "ERR_ACCT_NOT_EXIST",
    "err_info": "account not exist, check your key",
    "data":null
}

Param Style

Keys of JSON in request and response are in lower snake case, like snake_case.

Status of Transactions

Status of transactions, including deposit and withdrawal, could be:

TRANSFER_PENDING:
- APIs response: the withdrawal has been handled and will be broadcasted on cryptocurrency network soon
- withdrawal callback: the withdrawal has been broadcasted on network, but needs more confirmations
- deposit callback: the deposit has been detected, but needs more confirmations from cryptocurrency network
TRANSFER_SUCCESSFUL:
- APIs response: the withdrawal is handled off-chain instantly, in most case, address from and to are both in Dabank
- withdrawal callback: the withdrawal has enough confirmations from cryptocurrency network and can be considered stable
- deposit callback: the deposit has enough confirmations from cryptocurrency network and can be considered stable
TRANSFER_INVALID:
- withdrawal callback: unusually, the withdraw is later rejected or considered invalid for various reasons, e.g. risk management, cryptocurrency network down, network fork
- deposit callback: seldom, the deposit is considered invalid(most likely due to a network fork), note you may get several TRANSFER_PENDING callbacks before this.

APIs

test-APIs are hosted at http://dabank.gnway.cc:28080.
formal-APIs are hosted at https://api.dabank.io/.

Deposit Address Application

/api/v3/address

request:

key	type	compulsory	comment
symbol	string	✓	symbol for coin type identification
user_id	string	✓	unique id to distinguish user, needs to be the same for one specific user

{  
   "key":"your_api_id",
   "request_time":"1524290015",
   "sign":"data_signature",
   "symbol":"BTC",
   "user_id":"1234"
}

response:

key	type	comment
address	string	address for deposit

{
   "err_code":"",
   "err_info":"",
   "data":{  
      "address":"0x12345678910388342390012323"
   },
   "request_id":233049
}

Trigger a withdrawal

/api/v3/transfer

request:

key	type	compulsory	comment
symbol	string	✓	symbol for coin type identification
coins	string	✓	amount to withdraw
to	string	✓	destination address
from	string	✓	deposit address of the user withdrawing
unique_id	string	✓	generated by you, unique for one specific transaction, use the same one if you are re-trying this withdraw for some reason

{  
   "unique_id":"must_be_unique_use_the_same_one_when_retrying",
   "to":"0x12345678910388342390012323",
   "sign":"data_signature",
   "coins":"2.12345678",
   "symbol":"ETH",
   "from":"0xabc45678910388342390012323",
   "request_time":"1524298182",
   "key":"your_api_id"
}

response:

key	type	comment
transfer_id	string	internal transaction ID provided by Dabank, which you use to identity specific transaction
status	string	status of transaction

{  
   "err_code":"",
   "err_info":"",
   "data":{  
      "status":"TRANSFER_PENDING",
      "transfer_id":123
   },
   "request_id":233114
}

Get Balance of Your Supported Symbols

/api/v3/appAccount

request:

This API needs only basic auth param.

key	type	compulsory	comment

{  
  "key":"your_api_id",
  "request_time":"1524290015",
  "sign":"data_signature"
}

response:

key	type	comment
symbol	string	symbol for coin type identification
address	string	your app exclusive address
balance	string	your real-time balance

[
  {
  "symbol":"ETH",
  "address":"your_app_exclusive_eth_address",
  "balance":"234.5"
  },
  {
  "symbol":"BTC",
  "address":"your_app_exclusive_btc_address",
  "balance":"2.5"
  }
]

Get Statistics of Your Transactions between a Time Range

/api/v3/reconciliation

request:

key	type	compulsory	comment
start_time	string	✓	starting time of the time range(included)
end_time	string	✓	ending time of the time range(not included)

{  
  "key":"your_api_id",
  "request_time":"current_time_in_unix_second",
  "sign":"data_signature",
  "start_time": "started_time_in_unix_second",
  "end_time": "ended_time_in_unix_second"
}

response:

key	type	comment
symbol	string	symbol for coin type identification
fee_symbol	string	symbol in which fee incurs
fee	float64	fee accumulated during this time range

The rest keys should be self-documented.

{
    "err_code": "",
    "err_info": "",
    "data": {
        "statistics": [
            {
                "symbol": "XRP",
                "fee_symbol": "XRP",
                "fee": 0.43,
                "in_successful_coin": 34819.302933,
                "in_successful_count": 22,
                "in_pending_coin": 0,
                "in_pending_count": 0,
                "out_successful_coin": 161692.215504,
                "out_successful_count": 43,
                "out_failed_coin": 0,
                "out_failed_count": 0,
                "out_pending_coin": 0,
                "out_pending_count": 0
            },
            {
                            "symbol": "ETH",
                            "fee_symbol": "ETH",
                            "fee": 0.024,
                            "in_successful_coin": 114.48484908,
                            "in_successful_count": 9,
                            "in_pending_coin": 0,
                            "in_pending_count": 0,
                            "out_successful_coin": 39.17130422,
                            "out_successful_count": 6,
                            "out_failed_coin": 0,
                            "out_failed_count": 0,
                            "out_pending_coin": 0,
                            "out_pending_count": 0
            }
        ],
        "realtime_balance": [
            {
                "symbol": "XRP",
                "available_balance": 50000,
                "freeze": 0
            },
            {
                "symbol": "USDT(Omni)",
                "available_balance": 50000,
                "freeze": 0
            },
            {
                "symbol": "BTC",
                "available_balance": 50000,
                "freeze": 0
            },
            {
                "symbol": "ETH",
                "available_balance": 50000,
                "freeze": 0
            }
        ]
    },
    "request_id": 134
}

Validate An Address

Validate an address to ensure it is not malformed, note a "valid" address does not mean it is the "correct" address, the correction of an address as withdrawal destination is guaranteed by your users themselves.

/api/v3/checkAddress

request:

key	type	compulsory	comment
symbol	string	✓	symbol for coin type identification
address	string	✓	address to be checked

{  
  "key":"your_api_id",
  "request_time":"1524290015",
  "sign":"data_signature",
  "symbol":"ETH",
  "address":"12345678910388342390012321"
}

response:

key	type	comment
verify	string	Validation result, `Success` means valid, `Failure` means invalid
err_msg	string	when `Failure`, here lies the validation detail

{  
  "verify":"Failure",
  "err_msg":"ETH address should be started with \"0x\""
}

BCH CashAddr/Legacy Address Convention

For Bitcoin Cash(BCH), Dabank uses CashAddr across service, your users may use Legacy Address as withdrawal destination, in which case we shall convert them to CashAddr automatically.

We understand that there are lots of exchange not supporting withdrawal to CashAddr, so you may use this API to convert the deposit address Dabank provides to Legacy format, in favor for users in need.

/api/v3/bchAddrConvert

request:

key	type	compulsory	comment
address	string	✓	BCH CashAddr or Legacy Address

{  
  "key":"your_api_id",
  "request_time":"1524290015",
  "sign":"data_signature",
  "address":"1BpEi6DfDAUFd7GtittLSdBeYJvcoaVggu"
}

response:

key	type	comment
legacy_addr	string	your input in Legacy Address format
cash_addr	string	your input in CashAddr format(starting with `bitcoincash:` which is a inseparable part of address, do not drop that)

{  
  "legacy_addr":"1BpEi6DfDAUFd7GtittLSdBeYJvcoaVggu",
  "cash_addr":"bitcoincash:qpm2qsznhks23z7629mms6s4cwef74vcwvy22gdx6a"
}

Callbacks

You need to setup an endpoint to receive callbacks from Dabank, which is triggered in these cases:

deposit
- a new deposit arrival, pending or already confirmed
- the confirmation count of a pending deposit changes
- the confirmation count of a previously pending deposit changes, which makes it confirmed
withdrawal
- the confirmation count of a pending withdrawal changes
- the confirmation count of a previously pending withdrawal changes, which makes it confirmed

Security Note

Dabank uses your secret key to generate data signature in the way mentioned in APIs chapter. Check sign to avoid phishing, see chapter "Authentication".

HTTP POST Request from Dabank

key	type	comment
transfer_id	string	internal transaction ID provided by Dabank, which you use to identity specific transaction
symbol	string	symbol for coin type identification
confirms	string	confirmation count(not applicable for off-chain internal transaction in Dabank)
tx_id	string	transaction ID on cryptocurrency network
transfer_at	string	unix second of transaction initialization
confirm_at	string	unix second of transaction final confirmation
status	string	status of transaction
transfer_type	string	`IN` for incoming deposit, `OUT` for outgoing withdrawal
to	string	transaction destination address
from	string	transaction address of departure, may be empty when deposit
coins	string	amount of transaction, whose max precision is 8 decimals
fee	string	fee charged to you for this specific transaction
fee_symbol	string	the symbol of fee charged, normally we charge the mainnet coin for token withdrawal on that network

Callback request example on a withdrawal:

{  
   "transfer_id":"1365850",
   "symbol":"BTC",
   "tx_id":"7cee2e2055c85d40ab27f713d1bbcd7db2d07a8ab54483e7c423ed6cdc689007",
   "confirms":"2",
   "transfer_at":"1524298179",
   "confirm_at":"1524299426",
   "transfer_type":"OUT",
   "status":"TRANSFER_PENDING",
   "to":"1A3x2pU6gJKJAzc6XiZHKLhkBWSH6QkQo8",
   "from":"1G2BLexgX5dYwuzagBuSEp43Wy7Jgmm1mw",
   "coins":"2.73604069",
   "fee":"0.0008",
   "fee_symbol":"BTC",
   "request_time":"1524299426",
   "key":"your_api_id",
   "sign":"data_signature"
}

Callback request example on a successful withdrawal:

{  
   "transfer_id":"1365848",
   "symbol":"MGD",
   "tx_id":"bc2929b14ea303e198517d1550e30e1b8125f5f16fb373f7407f8a48cf605c7a",
   "confirms":"3",
   "transfer_at":"1524293497",
   "confirm_at":"1524294491",
   "transfer_type":"OUT",
   "status":"TRANSFER_SUCCESSFUL",
   "to":"MHBLixzhMs4RCfudx2jttU1SesxkjLxUrF",
   "from":"MPfFsz7GTSi4vQ5XEbMVRAZ67tDd6sQD21",
   "coins":"999.9",
   "fee":"0.001",
   "fee_symbol":"MGD",
   "request_time":"1524294491",
   "key":"your_api_id",
   "sign":"123"
}

Callback request example on a successful deposit:

{  
   "transfer_id":"1365849",
   "symbol":"ETH",
   "tx_id":"0x4ce2767bb3d039a5c62860cf51aec489ab1e287e62e9c60d1723186aee105bc7",
   "confirms":"13",
   "transfer_at":"1524296032",
   "confirm_at":"1524296243",
   "transfer_type":"IN",
   "status":"TRANSFER_SUCCESSFUL",
   "to":"0xc03db2681719eb3d41aa8ef5b23e11341fba57f0",
   "from":"",
   "coins":"2.997",
   "fee":"0",
   "fee_symbol":"ETH",
   "request_time":"1524296243",
   "key":"your_api_id",
   "sign":"123"
}

Your HTTP Response to Dabank

You need to response to HTTP request from Dabank with following content:

key	type	comment
result	string	`Success` when everything is fine, you may put error message when there is a problem

{  
   "result":"Success"
}

Dabank will retry the callback if you does not response with Success, the gap between each retry is 2^n in second, where n is the times of retry.

Notes

Monero Address

When withdrawing, user may provide a payment ID. In that case, you should join destination address and payment ID with $ as to to call API, like following:

address: 9wHNWjJ1Gnw7Yw1RjDLNiJ8yJw91xFCz4NvXCcQjzceiGqFXDcXuCqPckgi7pn1LA4FZ5EaAUd19meb8GXxCp3iFT2yZViw
payment ID: 662f879677b96d0919db4ae069d985e5e3dcf10c8429ed395a9a6e798bb4f9d1

to = address + $ + payment ID

to: 9wHNWjJ1Gnw7Yw1RjDLNiJ8yJw91xFCz4NvXCcQjzceiGqFXDcXuCqPckgi7pn1LA4FZ5EaAUd19meb8GXxCp3iFT2yZViw$662f879677b96d0919db4ae069d985e5e3dcf10c8429ed395a9a6e798bb4f9d1

If there is no payment ID, use destination address as to directly.

EOS Address

Dabank use memo to distinguish deposit of EOS and its tokens. For example, myeosaddress$9045 means the user need to send EOS to myeosaddress with memo 9045, where $ is the separator.

When a user is withdrawing, if a memo is provided, it should be attached to the destination address, with the separator $ like above mentioned.

Symbols Supported

Note: max decimals APIs and callbacks supported is 8.

symbol	token_of	decimals	contract_address
AAESP(WCG2)	WCG	4	14166359669915381351
ABB	ETH	18	0xbde6ff7ff944aa8ef554410572dfee184d25302a
ADD(EOS)	EOS(mainnet)	4	eosadddddddd
AIMS	ETH	8	0x9a1c7577a69ea9e296ef99bfb0eb6bedbe352a36
ALI	ETH	18	0x4289c043a12392f1027307fb58272d8ebd853912
ANTC	ETH	18	0xa8953562660855aaa3b2b2af9398e16246dfa597
AXPR	ETH	18	0xc39e626a04c5971d770e319760d7926502975e47
BCD		7
BCH		8
BFDT	ETH	18	0xd2d0f85b690604c245f61513bf4679b24ed64c35
BIDT	ETH	18	0x9206dadafd7555baf1bf004af18911152bf7f55b
BNB	ETH	18	0xb8c77482e45f1f44de1745f52c74426c631bdd52
BTC		8
BTK	ETH	18	0xdb8646f5b487b5dd979fac618350e85018f557d4
BTM	ETH	8	0xcb97e65f07da24d46bcdd078ebebd7c6e6e3d750
CDY	ETH	8	0x10f135ce102eee47dca8fe8e19dca6324dfbd684
CFUN(ERC20)	ETH	9	0xd6ed0e5d7f854b64b5e467a240a6c155c17cc6a2
CRE	ETH	18	0x61f33da40594cec1e3dc900faf99f861d01e2e7d
CTM(WCG2)	WCG2	4	7171868846042689336
CVN	ETH	5	0x62aaf435273bc4baa78dcebd6590042d7e58ba6f
DAILY	ETH	8	0xbc63f11d42860d7e41a4ce856581f0ce15ac4008
DATX	ETH	18	0xabbbb6447b68ffd6141da77c18c7b5876ed6c5ab
DCON		0
DKYC	ETH	18	0x38d1b0d157529bd5d936719a8a5f8379afb24faa
DRT(WCG2)	WCG2	4	7776054229687920460
EGT	ETH	18	0x8e1b448ec7adfc7fa35fc2e885678bd323176e34
EGTY	ETH	8	0x22c422d57638ff48af2e471e6f9fa5dc5b5edbd5
EOS(mainnet)		4	eosio.token
EQT(WCG2)	WCG2	4	17662811370611592334
ETH		18
FCS	ETH	18	0x574b5b500517ccad92c78573c7daf8be8cc0de19
FREC	ETH	18	0x17e67d1cb4e349b9ca4bc3e17c7df2a397a7bb64
GGP	ETH	5	0xcaa8a02ee6f6ed7cc12449041d4426fb10626b6f
GUSD	ETH	2	0x056fd409e1d7a124bd7017459dfea2f387b6d5cd
GVM(WCG2)	WCG2	4	11835391898538536373
HOTC	ETH	18	0x4d09c5e758ca68be27240f29fb681e5a5341ca98
HOTC(HOTCOIN)	ETH	0	0x5ebdc890cdb9312f9c8cd3d8ddc28fe9509f9923
HPB	ETH	18	0x38c6a68304cdefb9bec48bbfaaba5c5b47818bb2
HYB	ETH	8	0x00d53126139c547c7bd4f4285fc3756c2f081ab1
ICX	ETH	18	0xb5a5f22694352c15b00323844ad545abb2b11028
IDM	ETH	18	0x28b85bc9e851271214fe70f433874b9aedc5a94a
IOST	ETH	18	0xfa1a856cfa3409cfa145fa4e20eb270df3eb21ab
IPC		8
ITU	ETH	18	0xe9024599539b135c1eb889c1e70a71241631bc45
JLL	ETH	18	0x5661c46e366570360064ae1a50a17a7a1a8f3236
JOBS	ETH	8	0x994ad6d288f1797ad9e09682970ba474fc3e1fbc
KEY	ETH	18	0x4cc19356f2d37338b9802aa8e8fc58b0373296e7
LBA	ETH	8	0xae2592b477ac500068a7925ddfc9ee448fb58242
LMC		6
LPK	ETH	8	0x2cc71c048a804da930e28e93f3211dc03c702995
LRC	ETH	18	0xef68e7c694f40c8202821edf525de3782458639f
LTC		8
LYS	ETH	8	0xdd41fbd1ae95c5d9b198174a28e04be6b3d1aa27
MAT(WCG2)	WCG2	4	6316460833260624272
MBC	ETH	18	0x9c007b020685387fc93583d8a7eb97506df0f26a
MGD		8
MNR	ETH	18	0x5f824733d130ad85ec5e180368559cc89d14933d
MOS	ETH	18	0x420a43153da24b9e2aedcec2b8158a8653a3317e
MTR(WCG2)	WCG2	4	12642904667336691118
MUXE	ETH	18	0x515669d308f887fd83a471c7764f5d084886d34d
NRM	ETH	18	0x00000b233566fcc3825f94d68d4fc410f8cb2300
NSC	ETH	18	0x827b67176c20edf0f0d3eb76b0c53aa925018f2b
PAX	ETH	18	0x8e870d67f660d95d5be530380d0ec0bd388289e1
PBK	ETH	7	0x077dc3c0c9543df1cdd78386df3204e69e0dd274
PIPS	ETH	18	0x59db9fde270b39a07f38fa3106a760829074c7d9
POVR	ETH	18	0xc26925d537af8b3f315eeaf27113e84875b6f1b9
QOS	ETH	4	0x7b188a8b3a2113621895fb35fc67a779caffa92d
QTUM		8
READ	ETH	8	0x13d0bf45e5f319fa0b58900807049f23cae7c40d
RED	ETH	18	0x76960dccd5a1fe799f7c29be9f19ceb4627aeb2f
REDC	ETH	18	0xb563300a3bac79fc09b93b6f84ce0d4465a2ac27
RUFF	ETH	18	0xf278c1ca969095ffddded020290cf8b5c424ace2
SNCOIN	ETH	18	0x8c211128f8d232935afd80543e442f894a4355b7
TASH	ETH	18	0x002f06abe6995fd0ea4be011c53bfc989fa53ce0
THM	ETH	18	0xf1dd5964eabcc6e86230fa6f222677cfdaaf9f0e
TLT(WCG2)	WCG2	4	2721668346522778691
TRIO	ETH	18	0x8b40761142b9aa6dc8964e61d0585995425c3d94
TRUE	ETH	18	0xa4d17ab1ee0efdd23edc2869e7ba96b89eecf9ab
TRX	ETH	6	0xf230b790e05390fc8295f4d3f60332c93bed42e2
TRXmain		6
USDT	ETH	6	0xdac17f958d2ee523a2206206994597c13d831ec7
USDTK(WCG2)	WCG2	2	11164589766816208741
USDT(Omni)	BTC	8	31
USO	ETH	8	0x6c2428a17bb9074f93563575d9c5c492f268cfb4
VAR	ETH	18	0x828bfe8d626695a75184aa9b35cbdd1ec3eafaae
VNS	ETH	18	0x1e4e36b3f011d862fd70006804da8fcefe89d3d8
WCG2		8
WEN(WCG2)	WCG2	4	8342642094929787676
WOS(WCG2)	WCG2	4	411043316357352222
XLP	ETH	2	0x18017350089c7219f5b9a9b704c459c1a2814063
XMC		0
XMR		12
XNS	ETH	18	0xbf2f1e0e41f1e144bb1d5870e94324b9878dd95b
XRP		6
XRT	ETH	18	0x37d404a072056eda0cd10cb714d35552329f8500
XT	ETH	18	0x528d068ae69e90c90ad090b3c2b0d18241e9e9b5
ZRX	ETH	18	0xe41d2489571d322189246dafa5ebde1f4699f498

Version

Dabank v3.4 2019-01

dabankio / dabank-api-doc