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.

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 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.

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

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

keys

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

1. You use app_private_key(kept as secret) to sign your API requests, and you upload app_public_key to Dabank for request verification;
2. 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:

1. extract all keys and values in JSON's key-value pair(except sign) in the form of key=value, as array param;
2. sort param in lexical order;
3. join param with & to obtain string content;
4. calculate sha256 of content to get hashed;
5. 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;
6. encode rsa_sign with base64 and you get sign of your current request.

Steps to verify sign(for Dabank callback verification)

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

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

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

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

sign is generated in following steps:

1. extract all values except sign in JSON's key-value pair to array values;
2. put your secret(obtained from control panel of Dabank) into values;
3. sort values in lexical order;
4. join values with underline _ to obtain string content;
5. 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.

All responses are boxed in following object:

Example:

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

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

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.

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

/api/v3/address

• request:

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

• response:

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

/api/v3/transfer

• request:

{  
   "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:

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

/api/v3/appAccount

• request:

This API needs only basic auth param.

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

• response:

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

/api/v3/reconciliation

• request:

{  
  "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:

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 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":"your_api_id",
  "request_time":"1524290015",
  "sign":"data_signature",
  "symbol":"ETH",
  "address":"12345678910388342390012321"
}

• response:

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

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":"your_api_id",
  "request_time":"1524290015",
  "sign":"data_signature",
  "address":"1BpEi6DfDAUFd7GtittLSdBeYJvcoaVggu"
}

• response:

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

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

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

• 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"
}

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

{  
   "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.

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.

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.

Note: max decimals APIs and callbacks supported is 8.

Dabank v3.4 2019-01