- Get Started
- API Authentication
- Callback Integration
- Cryptocurrency Unit Conversion
- REST API
- Deposit Wallet API
- Create Deposit Addresses
- Verify Deposit Addresses
- Query Deposit Addresses
- Query Deployed Contract Deposit Addresses
- Query Pool Address
- Query Pool Address Balance
- Query Invalid Deposit Addresses
- Query Deposit Callback Detail
- Resend Deposit/Collection Callbacks
- Query Deposit Wallet Balance
- Update Deposit Address Label
- Query Deposit Address Label
- Withdraw Wallet API
- Withdraw Assets
- Cancel Withdrawal Request
- Query Latest Withdrawal Transaction State
- Query All Withdrawal Transaction States
- Query Withdrawal Transaction Event Logs
- Query Withdrawal Wallet Balance
- Query Withdrawal Callback Detail
- Set Withdrawal Request ACL
- Resend Withdrawal Callbacks
- Query Withdrawal Whitelist Configuration
- Add Withdrawal Whitelist Entry
- Remove Withdrawal Whitelist Entry
- Check Withdrawal Whitelist
- Query Withdrawal Whitelist
- Query Withdrawal Wallet Transaction History
- Sign Message
- Call Contract Read ABI
- Deposit / Withdraw Wallet Common API
- Vault Wallet API
- Common API
- Read-only API code API
- Deposit Wallet API
- Testing
- Appendix
- Setup a deposit wallet and configure it (via web control panel)
- Refer to CYBAVO VAULT SOFA User Manual for detailed steps.
- Request an API code/secret (via web control panel)
- Create deposit addresses (via CYBAVO SOFA API)
- Refer to Create deposit addresses API
- Waiting for the CYBAVO SOFA system detecting transactions to those deposit addresses
- Handle the deposit callback
- Use the callback data to update certain data on your system.
- Security Enhancement: Use the Query Callback Detail API to confirm the callback is sent from the CYBAVO SOFA system.
- Refer to Callback Integration for detailed information.
- Setup a withdrawal wallet and configure it (via web control panel)
- Refer to CYBAVO VAULT SOFA User Manual for detailed steps.
- Request an API code/secret (via web control panel)
- Make withdraw request (via CYBAVI SOFA API)
- Refer to Withdraw Assets API
- Security Enhancement: Also set the withdrawal authentication callback URL to authorize the withdrawal requests sent to the CYBAVO SOFA system.
- Waiting for the CYBAVO SOFA system broadcasting transactions to blockchain
- Handle the withdrawal callback
- Use the callback data to update certain data on your system.
- Refer to Callback Integration for detailed information.
- Use mock server to test CYBAVO SOFA API right away.
- To make a correct API call, refer to API Authentication.
- To handle callback correctly, refer to Callback Integration.
- The CYBAVO SOFA system verifies all incoming requests. All requests must include X-API-CODE, X-CHECKSUM headers otherwise caller will get a 403 Forbidden error.
- Request the API code/secret from the Wallet Details page on the web control panel for the first time.
- A paired refresh code can be used in the refresh API to acquire the new inactive API code/secret of the wallet.
- Before the inactive API code is activated, the currently activated API code is still valid.
- Once the paired API code becomes invalid, the paired refresh code will also become invalid.
- Put the API code in the X-API-CODE header.
- Use the inactivated API code in any request will activate it automatically. Once activated, the currently activated API code will immediately become invalid.
- Or you can explicitly call the activation API to activate the API code before use
- Calculate the checksum with the corresponding API secret and put the checksum in the X-CHECKSUM header.
- The checksum calculation will use all the query parameters, the current timestamp, user-defined random string and the post body (if any).
- Please refer to the code snippet on the github project to know how to calculate the checksum.
- A read-only API code can be used to call all the read functions of wallets.
- All the read functions will be labeled
VIEW
in front of the API definition.
- All the read functions will be labeled
- Use activation API with the
WALLET_ID
set asreadonly
to activate a read-only API code.- The full API path is
/v1/sofa/wallets/readonly/apisecret/activate
- After activation, the API code will remain valid until it is replaced by a newly activated read-only API code.
- The full API path is
- Use listing API to list all wallets that can be accessed through a read-only API code.
- Please note that the wallet must have an activated API code, otherwise no callback will be sent.
- Use the activation API to activate an API code.
- How to distinguish between deposit and withdrawal callbacks?
- Deposit Callback (callback type 1)
- The combination of txid and vout_index of the callback is unique, use this combined ID to identify the deposit request, not to use only the transaction ID (txid field). Because multiple deposit callbacks may have the same transaction ID, for example, BTC many-to-many transactions.
- Withdrawal Callback (callback type 2)
- The order_id of the callback is unique, use this ID to identify the withdrawal request.
- Deposit Callback (callback type 1)
-
To ensure that the callbacks have processed by callback handler, the CYBAVO SOFA system will continue to send the callbacks to the callback URL until a callback confirmation (HTTP/1.1 200 OK) is received or exceeds the number of retries (retry time interval: 1-3-5-15-45 mins).
- If all attempts fail, the callback will be set to a failed state, the callback handler can call the resend deposit callback or resend withdrawal callback API to request CYBAVO SOFA system to resend such kind of callback(s) or through the web control panel.
-
Refer to Callback Definition, Callback Type Definition for detailed definition.
-
Please refer to the code snippet on the github project to know how to validate the callback payload.
-
Best practice:
- While processing a deposit callback, in addition to verifying the checksum of the callback, use Query Callback Detail API with the serial ID of the callback to perform an additional confirmation.
processing state(1) -> transaction in pool state(2) -> transaction in chain state(3) -> repeats state 3 until the confirmation count is met
transaction in chain state(3) -> repeats state 3 until the confirmation count is met
Refer to Transaction State Definition for all transaction states definition.
- The amount and fees fields in the callback are in the smallest cryptocurrency unit, use
decimal
andfee_decimal
(in the addon field) fields of callback data to convert the unit.
- Refer to decimals of Currency Definition to convert main cryptocurrency unit.
- For the cryptocurrency token, use the token_decimals field of the Wallet Info API to convert cryptocurrency token unit.
Create deposit addresses on certain wallet. Once addresses are created, the CYBAVO SOFA system will callback when transactions are detected on these addresses.
TIP: Use the Verification API to verify the address before depositing assets.
POST /v1/sofa/wallets/WALLET_ID
/addresses
WALLET_ID
must be a deposit wallet ID
An example of the request:
/v1/sofa/wallets/107950/addresses
For BNB, XLM, XRP or EOS wallet:
{
"count": 2,
"memos": [
"10001",
"10002"
],
"labels": [
"note-for-001",
"note-for-002"
]
}
For wallet excepts BNB, XLM, XRP and EOS:
{
"count": 2,
"labels": [
"note-for-address-1",
"note-for-address-2"
]
}
The request includes the following parameters:
Field | Type | Note | Description |
---|---|---|---|
count | int | required, max 1000 |
Specify address count |
memos | array | required (creating BNB, XLM, XRP or EOS wallet) | Specify memos for BNB, XLM, XRP or EOS deposit wallet. Refer to Memo Requirement |
labels | array | optional | Specify the labels of the generated addresses or memos |
NOTE: The length of
memos
must equal tocount
while creating addresses for BNB, XLM, XRP or EOS wallet.NOTE: The memos(or called destination tags) of XRP must be strings that can be converted to numbers.
If use the
labels
to assign labels, the array length of the labels must equal tocount
. The label will be automatically synced to the child wallet.
An example of a successful response:
For BNB, XLM, XRP or EOS wallet:
{
"addresses": [
"10001",
"10002"
]
}
For wallet excepts BNB, XLM, XRP or EOS:
{
"addresses": [
"0x2E7248BBCD61Ad7C33EA183A85B1856bc02C40b6",
"0x4EB990D527c96c64eC5Bfb0D1e304840052d4975",
"0x86434604FF857702fbE11cBFf5aC7689Af19c4Ed"
]
}
For the ETH wallet that uses contract collection:
{
"txids": [
"0xe6dfe0d283690f636df5ea4b9df25552e6b576b88887bfb5837016cdd696e754",
"0xdb18fd33c9a6809bfc341a1c0b2c092be5a360f394c85367f9cf316579281ab4",
"0x18075ff1693026f93722f8b2cc0e29bf148ded5bce4dc173c8118951eceabe60",
"0x7c6acb506ef033c09f781cc5ad6b2d0a216346758d7f955e720d6bc7a52731a5",
"0x7da19f8c0d82cde16636da3307a6bef46eb9f398af3eb2362d230ce300509d63"
]
}
Use Query Deployed Contract Deposit Addresses API to query deployed contract addresses.
The response includes the following parameters:
Field | Type | Description |
---|---|---|
addresses | array | Array of just created deposit addresses |
txids | array | Array of transaction IDs used to deploy collection contract |
HTTP Code | Error Code | Error | Message | Description |
---|---|---|---|---|
403 | - | Forbidden. Invalid ID | - | No wallet ID found |
403 | - | Forbidden. Header not found | - | Missing X-API-CODE , X-CHECKSUM header or query param t |
403 | - | Forbidden. Invalid timestamp | - | The timestamp t is not in the valid time range |
403 | - | Forbidden. Invalid checksum | - | The request is considered a replay request |
403 | - | Forbidden. Invalid API code | - | X-API-CODE header contains invalid API code |
403 | - | Invalid API code for wallet {WALLET_ID} | - | The API code mismatched |
403 | - | Forbidden. Checksum unmatch | - | X-CHECKSUM header contains wrong checksum |
403 | - | Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) | - | Send requests too frequently |
403 | 112 | Invalid parameter | - | The count and the count of memos mismatched |
403 | 385 | API Secret not valid | - | Invalid API code permission |
403 | 706 | Exceed max allow wallet limitation, Upgrade your SKU to get more wallets | - | Reached the limit of the total number of deposit addresses |
400 | 421 | Mapped(Token) wallet not allow to create deposit addresses, please create the deposit wallet in parent wallet, the address will be synced to mapped wallet automatically | - | Only the parent wallet can create deposit addresses |
400 | 500 | insufficient fund | - | Insufficient balance to deploy collection contract |
400 | 703 | Operation failed | Error message returned by JSON parser | Malformatted post body |
400 | 818 | Destination Tag must be integer | - | Wrong XRP destination tag format |
400 | 945 | The max length of BNB memo is 256 chars | - | Reached the limit of the length of BNB memo |
400 | 946 | The max length of EOS memo is 128 chars | - | Reached the limit of the length of EOS memo |
400 | 947 | The max length of XRP destination tag is 20 chars | - | Reached the limit of the length of XRP destination tag |
400 | 948 | The max length of XLM memo is 20 chars | - | Reached the limit of the length of XLM memo |
404 | 304 | Wallet ID invalid | archived wallet or wrong wallet type | The wallet is not allowed to perform this request |
Verify that these addresses belong to a deposit wallet.
VIEW
POST /v1/sofa/wallets/WALLET_ID
/receiver/addresses/verify
WALLET_ID
must be a deposit wallet ID
An example of the request:
/v1/sofa/wallets/98675/receiver/addresses/verify
{
"addresses": [
"0x46d4AD967F68253f61D45a044dC7dC7B13E5A4B3",
"0x107FF19Ea5fB7de78392e7AcC2A2C7eace891bDc"
]
}
The request includes the following parameters:
Field | Type | Note | Description |
---|---|---|---|
addresses | array | required | Specify the addresses to be verified |
If the address can not be found or invalid, it will not be listed in the response.
An example of a successful response:
{
"addresses": {
"0x107FF19Ea5fB7de78392e7AcC2A2C7eace891bDc": {
"create_time": "2021-12-05T16:23:20Z",
"label": "987444413"
},
"0x46d4AD967F68253f61D45a044dC7dC7B13E5A4B3": {
"create_time": "2021-12-05T16:23:20Z",
"label": ""
}
}
}
The response includes the following parameters:
Field | Type | Description |
---|---|---|
addresses | key-value pairs | The address-info pairs |
label | string | Associated label |
create_time | string | Address creation time (UTC) |
HTTP Code | Error Code | Error | Message | Description |
---|---|---|---|---|
403 | - | Forbidden. Invalid ID | - | No wallet ID found |
403 | - | Forbidden. Header not found | - | Missing X-API-CODE , X-CHECKSUM header or query param t |
403 | - | Forbidden. Invalid timestamp | - | The timestamp t is not in the valid time range |
403 | - | Forbidden. Invalid checksum | - | The request is considered a replay request |
403 | - | Forbidden. Invalid API code | - | X-API-CODE header contains invalid API code |
403 | - | Invalid API code for wallet {WALLET_ID} | - | The API code mismatched |
403 | - | Forbidden. Checksum unmatch | - | X-CHECKSUM header contains wrong checksum |
403 | - | Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) | - | Send requests too frequently |
403 | 385 | API Secret not valid | - | Invalid API code permission |
400 | 112 | Invalid parameter | - | Malformatted post body |
404 | 304 | Wallet ID invalid | - | The wallet is not allowed to perform this request |
Query the deposit addresses created by the Create Deposit Addresses API.
VIEW
GET /v1/sofa/wallets/WALLET_ID
/addresses?start_index=from
&request_number=count
WALLET_ID
must be a deposit wallet ID
An example of the request:
/v1/sofa/wallets/179654/addresses?start_index=0&request_number=3
--- THEN ---
/v1/sofa/wallets/179654/addresses?start_index=3&request_number=3
The request includes the following parameters:
Field | Type | Note | Description |
---|---|---|---|
start_index | int | optional, default 0 |
Specify address start index |
request_number | int | optional, default 1000 , max 5000 |
Request address count |
An example of a successful response:
{
"wallet_id": 179654,
"wallet_count": 6,
"wallet_address": [
{
"currency": 60,
"token_address": "",
"address": "0x8c42fD03A5cfba7C3Cd97AB8a09e1a3137Ef33C3",
"memo": ""
},
{
"currency": 60,
"token_address": "",
"address": "0x4d3EB54b602BF4985CE457089F9fB084Af597A2C",
"memo": ""
},
{
"currency": 60,
"token_address": "",
"address": "0x74dc3fB523295C87C0b93E48744Ce94fe3a8Ef5e",
"memo": ""
}
]
}
--- THEN ---
{
"wallet_id": 179654,
"wallet_count": 6,
"wallet_address": [
{
"currency": 60,
"token_address": "",
"address": "0x6d68443D6564cF257A48c1b16aa6d0EF13c5A719",
"memo": ""
},
{
"currency": 60,
"token_address": "",
"address": "0x26F103322B6f0ed2D35B85F1611589c92F023986",
"memo": ""
},
{
"currency": 60,
"token_address": "",
"address": "0x2b91918Bee4411DaD6293EA5d6D38251E72723Ca",
"memo": ""
}
]
}
The response includes the following parameters:
Field | Type | Description |
---|---|---|
wallet_id | int64 | ID of request wallet |
wallet_address | array | Array of wallet addresses |
wallet_count | int64 | Total count of deposit addresses |
Refer to Currency Definition or here for more detailed currency definitions
If this is an ETH contract collection deposit wallet, only the deployed address will be returned.
HTTP Code | Error Code | Error | Message | Description |
---|---|---|---|---|
403 | - | Forbidden. Invalid ID | - | No wallet ID found |
403 | - | Forbidden. Header not found | - | Missing X-API-CODE , X-CHECKSUM header or query param t |
403 | - | Forbidden. Invalid timestamp | - | The timestamp t is not in the valid time range |
403 | - | Forbidden. Invalid checksum | - | The request is considered a replay request |
403 | - | Forbidden. Invalid API code | - | X-API-CODE header contains invalid API code |
403 | - | Invalid API code for wallet {WALLET_ID} | - | The API code mismatched |
403 | - | Forbidden. Checksum unmatch | - | X-CHECKSUM header contains wrong checksum |
403 | - | Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) | - | Send requests too frequently |
403 | 385 | API Secret not valid | - | Invalid API code permission |
404 | 304 | Wallet ID invalid | - | The wallet is not allowed to perform this request |
Query deployed contract deposit addresses created by the Create Deposit Addresses API.
VIEW
GET /v1/sofa/wallets/WALLET_ID
/addresses/contract_txid?txids=txid1,txid2
WALLET_ID
must be an ETH contract collection deposit wallet IDOnly deployed addresses will be returned
An example of the request:
/v1/sofa/wallets/179654/addresses/contract_txid?txids=0xe6dfe0d283690f636df5ea4b9df25552e6b576b88887bfb5837016cdd696e754,0xdb18fd33c9a6809bfc341a1c0b2c092be5a360f394c85367f9cf316579281ab4
The request includes the following parameters:
Field | Type | Note | Description |
---|---|---|---|
txids | string | requried, max 10 transaction IDs |
Transaction ID used to deploy collection contract |
An example of a successful response:
{
"addresses": {
"0xdb18fd33c9a6809bfc341a1c0b2c092be5a360f394c85367f9cf316579281ab4": {
"address": "0x00926cE2BbF56317c72234a0Fb8A65A1A15F7103",
"currency": 60,
"memo": "",
"token_address": ""
},
"0xe6dfe0d283690f636df5ea4b9df25552e6b576b88887bfb5837016cdd696e754": {
"address": "0xf3747e3edbd8B8414718dd51330415c171e79208",
"currency": 60,
"memo": "",
"token_address": ""
}
}
}
The response includes the following parameters:
Field | Type | Description |
---|---|---|
addresses | map object | The map KEY is Transaction ID used to deploy collection contract and the map VALUE is the address information |
HTTP Code | Error Code | Error | Message | Description |
---|---|---|---|---|
403 | - | Forbidden. Invalid ID | - | No wallet ID found |
403 | - | Forbidden. Header not found | - | Missing X-API-CODE , X-CHECKSUM header or query param t |
403 | - | Forbidden. Invalid timestamp | - | The timestamp t is not in the valid time range |
403 | - | Forbidden. Invalid checksum | - | The request is considered a replay request |
403 | - | Forbidden. Invalid API code | - | X-API-CODE header contains invalid API code |
403 | - | Invalid API code for wallet {WALLET_ID} | - | The API code mismatched |
403 | - | Forbidden. Checksum unmatch | - | X-CHECKSUM header contains wrong checksum |
403 | - | Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) | - | Send requests too frequently |
403 | 385 | API Secret not valid | - | Invalid API code permission |
404 | 304 | Wallet ID invalid | - | The wallet is not allowed to perform this request |
Get the pool address of a deposit wallet. The pool address has different functionality in different cryptocurrencies.
In BTC or ETH, the cryptocurrency in the pool address will be used to pay for token transfer(ex. USDT-Omni, ERC20).
BCH/BSV need at least 0.01 BCH/BSV in the pool address for polluting the non-fork coin and make the collection successfully.
In EOS, XRP, XLM or BNB, the pool address is the user's deposit address. All user deposits will be distinguished by memo / tag field.
LTC, DOGE, DASH, DOT(WND), FIL. SOL and ADA does not support pool address.
VIEW
GET /v1/sofa/wallets/WALLET_ID
/pooladdress
WALLET_ID
must be a deposit wallet ID
An example of the request:
/v1/sofa/wallets/179654/pooladdress
An example of a successful response:
{
"address": "0x36099775afa8d6363aC8e5d0fC698306C021a858"
}
The response includes the following parameters:
Field | Type | Description |
---|---|---|
address | string | Pool address of wallet |
HTTP Code | Error Code | Error | Message | Description |
---|---|---|---|---|
403 | - | Forbidden. Invalid ID | - | No wallet ID found |
403 | - | Forbidden. Header not found | - | Missing X-API-CODE , X-CHECKSUM header or query param t |
403 | - | Forbidden. Invalid timestamp | - | The timestamp t is not in the valid time range |
403 | - | Forbidden. Invalid checksum | - | The request is considered a replay request |
403 | - | Forbidden. Invalid API code | - | X-API-CODE header contains invalid API code |
403 | - | Invalid API code for wallet {WALLET_ID} | - | The API code mismatched |
403 | - | Forbidden. Checksum unmatch | - | X-CHECKSUM header contains wrong checksum |
403 | - | Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) | - | Send requests too frequently |
403 | 385 | API Secret not valid | - | Invalid API code permission |
400 | 703 | this wallet does not support pool address | - | - |
404 | 304 | Wallet ID invalid | - | The wallet is not allowed to perform this request |
Get the pool address balance of a deposit wallet.
VIEW
GET /v1/sofa/wallets/WALLET_ID
/pooladdress/balance
WALLET_ID
must be a deposit wallet ID
An example of the request:
/v1/sofa/wallets/179654/pooladdress/balance
An example of a successful response:
{
"balance": "0.515",
"currency": 60,
"unconfirm_balance": "0",
"wallet_address": "0xb6ad80c96D093EA584AfcB9443927812d3e4Bd94"
}
The response includes the following parameters:
Field | Type | Description |
---|---|---|
balance | string | Pool address balance |
unconfirm_balance | string | Unconfirmed pool address balance |
currency | int64 | Cryptocurrency of the wallet |
wallet_address | string | Pool address of the wallet |
HTTP Code | Error Code | Error | Message | Description |
---|---|---|---|---|
403 | - | Forbidden. Invalid ID | - | No wallet ID found |
403 | - | Forbidden. Header not found | - | Missing X-API-CODE , X-CHECKSUM header or query param t |
403 | - | Forbidden. Invalid timestamp | - | The timestamp t is not in the valid time range |
403 | - | Forbidden. Invalid checksum | - | The request is considered a replay request |
403 | - | Forbidden. Invalid API code | - | X-API-CODE header contains invalid API code |
403 | - | Invalid API code for wallet {WALLET_ID} | - | The API code mismatched |
403 | - | Forbidden. Checksum unmatch | - | X-CHECKSUM header contains wrong checksum |
403 | - | Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) | - | Send requests too frequently |
403 | 385 | API Secret not valid | - | Invalid API code permission |
404 | 304 | Wallet ID invalid | - | The wallet is not allowed to perform this request |
When an abnormal deposit is detected, the CYBAVO SOFA system will set the deposit address to invalid. Use this API to obtain the all invalid deposit addresses for further usage.
VIEW
GET /v1/sofa/wallets/WALLET_ID
/addresses/invalid-deposit
WALLET_ID
must be a deposit wallet ID
An example of the request:
/v1/sofa/wallets/179654/addresses/invalid-deposit
An example of a successful response:
{
"addresses": ["0x5dB3d8C70dAa9C919F9962221c2fDDbe8EBAa5F2"]
}
The response includes the following parameters:
Field | Type | Description |
---|---|---|
addresses | array | Array of invalid deposit address |
HTTP Code | Error Code | Error | Message | Description |
---|---|---|---|---|
403 | - | Forbidden. Invalid ID | - | No wallet ID found |
403 | - | Forbidden. Header not found | - | Missing X-API-CODE , X-CHECKSUM header or query param t |
403 | - | Forbidden. Invalid timestamp | - | The timestamp t is not in the valid time range |
403 | - | Forbidden. Invalid checksum | - | The request is considered a replay request |
403 | - | Forbidden. Invalid API code | - | X-API-CODE header contains invalid API code |
403 | - | Invalid API code for wallet {WALLET_ID} | - | The API code mismatched |
403 | - | Forbidden. Checksum unmatch | - | X-CHECKSUM header contains wrong checksum |
403 | - | Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) | - | Send requests too frequently |
403 | 385 | API Secret not valid | - | Invalid API code permission |
404 | 304 | Wallet ID invalid | - | The wallet is not allowed to perform this request |
Query the detailed information of the deposit callback by the tx ID and the vout index.
VIEW
GET /v1/sofa/wallets/WALLET_ID
/receiver/notifications/txid/TX_ID
/VOUT_INDEX
An example of the request:
/v1/sofa/wallets/179654/receiver/notifications/txid/0xb72a81976f780445decd13a35c24974c4e32665cb57d79b3f7a601c775f6a7d8/0
An example of a successful response:
{
"notification": {
"addon": {},
"amount": "2000000000000000000",
"block_height": 7757485,
"broadcast_at": 1587441501,
"chain_at": 1587441501,
"confirm_blocks": 166027,
"currency": "ETH",
"fees": "126000000000000",
"from_address": "0x8382Cc1B05649AfBe179e341179fa869C2A9862b",
"memo": "",
"order_id": "",
"processing_state": 2,
"serial": 90000000547,
"state": 3,
"tindex": 27,
"to_address": "0x32d638773cB85965422b3B98e9312Fc9392307BC",
"txid": "0xb72a81976f780445decd13a35c24974c4e32665cb57d79b3f7a601c775f6a7d8",
"type": 1,
"vout_index": 0,
"wallet_id": 179654
}
}
The response includes the following parameters:
Field | Type | Description |
---|---|---|
notification | object | Refer to Callback Definition |
HTTP Code | Error Code | Error | Message | Description |
---|---|---|---|---|
403 | - | Forbidden. Invalid ID | - | No wallet ID found |
403 | - | Forbidden. Header not found | - | Missing X-API-CODE , X-CHECKSUM header or query param t |
403 | - | Forbidden. Invalid timestamp | - | The timestamp t is not in the valid time range |
403 | - | Forbidden. Invalid checksum | - | The request is considered a replay request |
403 | - | Forbidden. Invalid API code | - | X-API-CODE header contains invalid API code |
403 | - | Invalid API code for wallet {WALLET_ID} | - | The API code mismatched |
403 | - | Forbidden. Checksum unmatch | - | X-CHECKSUM header contains wrong checksum |
403 | - | Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) | - | Send requests too frequently |
403 | 385 | API Secret not valid | - | Invalid API code permission |
404 | 304 | Wallet ID invalid | - | The wallet is not allowed to perform this request or the callback (txid+vout_index) not found |
The callback handler can call this API to resend pending, risk-controlled or failed deposit/collection callbacks.
Refer to Callback Integration for callback rules.
The resend operation could be requested on the web control panel as well.
POST /v1/sofa/wallets/WALLET_ID
/collection/notifications/manual
WALLET_ID
must be a deposit wallet ID
An example of the request:
/v1/sofa/wallets/179654/collection/notifications/manual
{
"notification_id": 0
}
The request includes the following parameters:
Field | Type | Note | Description |
---|---|---|---|
notification_id | int64 | required, 0 means all | Specify callback ID to resend |
This ID equal to the serial field of callback data.
An example of a successful response:
{
"count": 0
}
The response includes the following parameters:
Field | Type | Description |
---|---|---|
count | int | Count of callbacks just resent |
HTTP Code | Error Code | Error | Message | Description |
---|---|---|---|---|
403 | - | Forbidden. Invalid ID | - | No wallet ID found |
403 | - | Forbidden. Header not found | - | Missing X-API-CODE , X-CHECKSUM header or query param t |
403 | - | Forbidden. Invalid timestamp | - | The timestamp t is not in the valid time range |
403 | - | Forbidden. Invalid checksum | - | The request is considered a replay request |
403 | - | Forbidden. Invalid API code | - | X-API-CODE header contains invalid API code |
403 | - | Invalid API code for wallet {WALLET_ID} | - | The API code mismatched |
403 | - | Forbidden. Checksum unmatch | - | X-CHECKSUM header contains wrong checksum |
403 | - | Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) | - | Send requests too frequently |
403 | 385 | API Secret not valid | - | Invalid API code permission |
400 | 112 | Invalid parameter | - | Malformatted post body |
404 | 304 | Wallet ID invalid | - | The wallet is not allowed to perform this request |
Get the deposit wallet balance.
VIEW
GET /v1/sofa/wallets/WALLET_ID
/receiver/balance
WALLET_ID
must be a deposit wallet ID
An example of the request:
/v1/sofa/wallets/959272/receiver/balance
An example of a successful response:
{
"currency": 60,
"token_address": "",
"balance": "0.619673333517576",
"token_balance": ""
}
The response includes the following parameters:
Field | Type | Description |
---|---|---|
currency | int64 | Registered coin types. Refer to Currency Definition |
token_address | string | Token contract address |
balance | string | Deposit wallet balance |
token_balance | string | Deposit wallet token balance |
HTTP Code | Error Code | Error | Message | Description |
---|---|---|---|---|
403 | - | Forbidden. Invalid ID | - | No wallet ID found |
403 | - | Forbidden. Header not found | - | Missing X-API-CODE , X-CHECKSUM header or query param t |
403 | - | Forbidden. Invalid timestamp | - | The timestamp t is not in the valid time range |
403 | - | Forbidden. Invalid checksum | - | The request is considered a replay request |
403 | - | Forbidden. Invalid API code | - | X-API-CODE header contains invalid API code |
403 | - | Invalid API code for wallet {WALLET_ID} | - | The API code mismatched |
403 | - | Forbidden. Checksum unmatch | - | X-CHECKSUM header contains wrong checksum |
403 | - | Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) | - | Send requests too frequently |
403 | 385 | API Secret not valid | - | Invalid API code permission |
404 | 304 | Wallet ID invalid | - | The wallet is not allowed to perform this request |
Update the label of the deposit address.
POST /v1/sofa/wallets/WALLET_ID
/addresses/label
WALLET_ID
must be a deposit wallet IDThe label will be automatically synced between the parent and child wallet.
An example of the request:
/v1/sofa/wallets/98675/addresses/label
{
"address": "0x2B974a3De0b491bB26e0bF146E6cDaC36EFD574a",
"label": "take-some-notes"
}
The request includes the following parameters:
Field | Type | Note | Description |
---|---|---|---|
address | string | required | Specify address to update the label |
label | string | optional, set empty to clear the label | Specify the label of the address |
Status code 200 represnts a successful operation
HTTP Code | Error Code | Error | Message | Description |
---|---|---|---|---|
403 | - | Forbidden. Invalid ID | - | No wallet ID found |
403 | - | Forbidden. Header not found | - | Missing X-API-CODE , X-CHECKSUM header or query param t |
403 | - | Forbidden. Invalid timestamp | - | The timestamp t is not in the valid time range |
403 | - | Forbidden. Invalid checksum | - | The request is considered a replay request |
403 | - | Forbidden. Invalid API code | - | X-API-CODE header contains invalid API code |
403 | - | Invalid API code for wallet {WALLET_ID} | - | The API code mismatched |
403 | - | Forbidden. Checksum unmatch | - | X-CHECKSUM header contains wrong checksum |
403 | - | Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) | - | Send requests too frequently |
403 | 385 | API Secret not valid | - | Invalid API code permission |
400 | 112 | Invalid parameter | - | Malformatted post body |
404 | 304 | Wallet ID invalid | - | The wallet is not allowed to perform this request |
404 | 112 | Invalid parameter | - | The address can not be found |
Query the labels of the deposit addresses.
VIEW
POST /v1/sofa/wallets/WALLET_ID
/addresses/get_labels
WALLET_ID
must be a deposit wallet ID
An example of the request:
/v1/sofa/wallets/98675/addresses/get_labels
{
"addresses": [
"0x2B974a3De0b491bB26e0bF146E6cDaC36EFD574a",
"0xF401AC94D9672e79c68e56A6f822b666E5A7d644"
]
}
The request includes the following parameters:
Field | Type | Note | Description |
---|---|---|---|
addresses | array | required | Specify the addresses to query labels |
An example of a successful response:
{
"labels": {
"0x2B974a3De0b491bB26e0bF146E6cDaC36EFD574a": "take-some-notes",
"0xF401AC94D9672e79c68e56A6f822b666E5A7d644": ""
}
}
The response includes the following parameters:
Field | Type | Description |
---|---|---|
labels | key-value pairs | The address-label pairs |
If the address can not be found, it will not be listed in the response.
HTTP Code | Error Code | Error | Message | Description |
---|---|---|---|---|
403 | - | Forbidden. Invalid ID | - | No wallet ID found |
403 | - | Forbidden. Header not found | - | Missing X-API-CODE , X-CHECKSUM header or query param t |
403 | - | Forbidden. Invalid timestamp | - | The timestamp t is not in the valid time range |
403 | - | Forbidden. Invalid checksum | - | The request is considered a replay request |
403 | - | Forbidden. Invalid API code | - | X-API-CODE header contains invalid API code |
403 | - | Invalid API code for wallet {WALLET_ID} | - | The API code mismatched |
403 | - | Forbidden. Checksum unmatch | - | X-CHECKSUM header contains wrong checksum |
403 | - | Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) | - | Send requests too frequently |
403 | 385 | API Secret not valid | - | Invalid API code permission |
400 | 112 | Invalid parameter | - | Malformatted post body |
404 | 304 | Wallet ID invalid | - | The wallet is not allowed to perform this request |
To withdraw assets from an withdrawal wallet, the caller must to provide an unique order_id for each request, the CYBAVO SOFA system will send the callback with the unique order_id when the withdrawal is success (from in pool
state to in chain
state).
By default, the withdraw API will perform the address check to verify that the outgoing address is good or not. If the address in the request is marked as a problematic address, the request will be aborted. The error message will identify the problematic addresses. Set the ignore_black_list
to true to skip the address check.
The withdrawal API can also interact with the contracts (ERC/BEP 721/1155) deployed in the SOFA system.
POST /v1/sofa/wallets/WALLET_ID
/sender/transactions
WALLET_ID
must be a withdrawal wallet IDThe order_id must be prefixed. Find prefix from corresponding wallet detail on web control panel.
If withdraw BNB or XRP, this API will check whether the destination addresse needs memo / destination tag or not. If the address does need memo / destination tag, the API will fail without memo / destination tag specified.
An example of the request:
The prefix is 888888_ in following sample request.
/v1/sofa/wallets/68451/sender/transactions
{
"requests": [
{
"order_id": "888888_1",
"address": "0x83eE561B2aBD000FF00d6ca22f38b29d4a760d4D",
"amount": "0.0001",
"memo": "memo-001",
"user_id": "USER01",
"message": "message-001",
"block_average_fee": 5
},
{
"order_id": "888888_2",
"address": "0xf16B7B8900F0d2f682e0FFe207a553F52B6C7015",
"amount": "0.0002",
"manual_fee": 50
},
{
"order_id": "888888_3",
"address": "0x9638fa816ccd35389a9a98a997ee08b5321f3eb9",
"amount": "0.0002",
"message": "message-003"
},
{
"order_id": "888888_4",
"address": "0x2386b18e76184367b844a402332703dd2eec2a90",
"amount": "0",
"contract_abi":"create:0x000000000000000000000000000000000000000000000000000000000000138800000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000000"
"user_id": "USER04",
"ignore_gas_estimate_fail": true
},
{
"order_id": "888888_5",
"address": "0x2386b18e76184367b844a402332703dd2eec2a90",
"amount": "1",
"token_id": "985552421"
}
],
"ignore_black_list": false
}
The request includes the following parameters:
Field | Type | Note | Description |
---|---|---|---|
order_id | string | required, max 255 chars |
Specify an unique ID, order ID must be prefixed |
address | string | required | Outgoing address (address must be a contract address, if the contract_abi is not empty) |
amount | string | required | Withdrawal amount |
contract_abi | string | required, if calls contract ABI | Specify the ABI method and the parameters, in the format ABI_method:parameters |
memo | string | optional | Memo on blockchain (This memo will be sent to blockchain). Refer to Memo Requirement |
user_id | string | optional | Specify certain user |
message | string | optional | Message (This message only saved on CYBAVO, not sent to blockchain) |
block_average_fee | int | optional, range 1~100 |
Use average blockchain fee within latest N blocks. This option does not work for XRP, XLM, BNB, DOGE, EOS, TRX, ADA, DOT and SOL cryptocurrencies. |
manual_fee | int | optional, range 1~2000 |
Specify blockchain fee in smallest unit of wallet currency (For ETH/BSC/HECO/OKT/OP/ARB/CELO/FTM/PALM, the unit is gwei. The unit returned by the Query Average Fee API is wei, divided by 1000000000 to get the correct unit. . This option does not work for XRP, XLM, BNB, DOGE, EOS, TRX, ADA, DOT and SOL cryptocurrencies. |
token_id | string | optional | Specify the token ID to be transferred |
ignore_gas_estimate_fail | boolean | optional, default false |
FOR DEBUG PURPOSE ONLY. After setting, the ABI EVM gas estimation will not be performed(Apply to individual order). |
ignore_black_list | boolean | optional, default false |
After setting, the address check will not be performed. Apply to all orders. |
The order_id must be prefixed. Find prefix from corresponding wallet detail on web control panel
block_average_fee and manual_fee are mutually exclusive configurations. If neither of these fields is set, the fee will refer to corresponding withdrawal policy of the withdrawal wallet.
The format of the
contract_abi
isABI_method:hex_parameters
, for example: create:0x000000000000000000000000000000000000000000000000000000000000138800000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000000. The parameters must be encoded by web3.eth.abi.encodeParameters() of web3.js.Only ERC721/1155 wallet can use
token_id
to transfer token. For ERC721 wallets, iftoken_id
is specified, the amount will be ignored.The
block_average_fee
andmanual_fee
do not work for XRP, XLM, BNB, DOGE, EOS, TRX, ADA, DOT and SOL cryptocurrencies.
An example of a successful response:
{
"results": {
"1": 20000000001,
"2": 20000000002
}
}
The response includes the following parameters:
Field | Type | Description |
---|---|---|
results | array | Array of withdraw result (order ID/withdraw transaction ID pair), if succeeds |
An example response of the request contains problematic addresses:
{
"error_code": 827,
"error": "Outgoing address in black list, abort transaction",
"blacklist": {
"0x83eE561B2aBD000FF00d6ca22f38b29d4a760d4D": [
"Involve phishing activity",
"Involve cybercrime related"
]
}
}
The response includes the following parameters:
Field | Type | Description |
---|---|---|
error_code | int | The error code |
error | string | The error message |
blacklist | object | The object describes all problematic addresses and their causes. |
HTTP Code | Error Code | Error | Message | Description |
---|---|---|---|---|
403 | - | Forbidden. Invalid ID | - | No wallet ID found |
403 | - | Forbidden. Header not found | - | Missing X-API-CODE , X-CHECKSUM header or query param t |
403 | - | Forbidden. Invalid timestamp | - | The timestamp t is not in the valid time range |
403 | - | Forbidden. Invalid checksum | - | The request is considered a replay request |
403 | - | Forbidden. Invalid API code | - | X-API-CODE header contains invalid API code |
403 | - | Invalid API code for wallet {WALLET_ID} | - | The API code mismatched |
403 | - | Forbidden. Checksum unmatch | - | X-CHECKSUM header contains wrong checksum |
403 | - | Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) | - | Send requests too frequently |
403 | 385 | API Secret not valid | - | Invalid API code permission |
403 | 827 | Outgoing address in black list, abort transaction | - | Some outgoing addresses are blacklisted, examine the response 'blacklist' field for detailed information |
400 | 112 | Invalid parameter | - | Malformatted post body |
400 | 112 | Invalid parameter | the maximum request limit is exceeded | - |
400 | 955 | There is no content in your withdrawal request, please check your input | - | The post body of request doesn't conform the API request specification |
400 | 703 | Operation failed | order_id must start with {ORDERID_PREFIX} | The prefix of order_id is incorrect |
400 | 703 | Operation failed | order_id: {ORDER_ID} - the character \ or / is prohibited | {ORDER_ID} is invalid |
400 | 703 | Operation failed | order_id: {ORDER_ID} is invalid | {ORDER_ID} is invalid |
400 | 703 | Operation failed | order_id: {ORDER_ID} - memo is required | The outgoing address of {ORDER_ID} needs memo specified |
400 | 703 | Operation failed | order_id: {ORDER_ID} - destination tag is required | The outgoing address of {ORDER_ID} needs destination tag specified |
400 | 703 | Operation failed | order_id: {ORDER_ID} - invalid block_average_fee | The block_average_fee is out of range |
400 | 703 | Operation failed | order_id: {ORDER_ID} - invalid manual_fee | The manual_fee is out of range |
400 | 399 | Duplicated entry: {ORDER_ID} | - | The {ORDER_ID} is duplicated |
400 | 945 | The max length of BNB memo is 256 chars | - | Reached the limit of the length of BNB memo |
400 | 946 | The max length of EOS memo is 128 chars | - | Reached the limit of the length of EOS memo |
400 | 947 | The max length of XRP destination tag is 20 chars | - | Reached the limit of the length of XRP destination tag |
400 | 948 | The max length of XLM memo is 20 chars | - | Reached the limit of the length of XLM memo |
400 | 818 | Destination Tag must be integer | - | Wrong XRP destination tag format |
400 | 944 | The max length of order id is 255 chars | - | Reached the limit of the length of order_id |
400 | 703 | Operation failed | Detailed error message | Failed to connect to authentication callback URL |
400 | 703 | Operation failed | The withdrawal request has been rejected, {RESPONSE_BODY} | The withdrawal request has been rejected by the authentication callback |
400 | 703 | Operation failed | The withdrawal request has been rejected, unexpected response {HTTP_CODE}: {RESPONSE_BODY} | The authentication callback URL returned status code other than 200 or 400 |
400 | 703 | Operation failed | Unrecognized response: {RESPONSE_BODY}, 'OK' expected | The returned status code is 200 but the body is not OK |
400 | 703 | Operation failed | request IP ({IPv4}) not in ACL | The request IP not in the withdrawal ACL |
400 | 703 | Operation failed | invalid amount {AMOUNT} | The requested amount is not a valid number |
400 | 703 | Operation failed | invalid amount decimals {AMOUNT} | The decimals of the requested amount exceeds the valid range |
400 | 955 | There is no content in your withdrawal request, please check your input | - | No orders found in the request that may be caused by an incorrectly formatted post body |
404 | 304 | Wallet ID invalid | - | The wallet is not allowed to perform this request |
404 | 312 | Policy not found | no active withdrawal policy found | No active withdrawal policy found |
To cancel the withdrawal request which state is Init
or Failed
. The request state can be checked on web control panel or query through this API (represents state
= 0 or 5 ).
POST /v1/sofa/wallets/WALLET_ID
/sender/transactions/ORDER_ID
/cancel
WALLET_ID
must be a withdrawal wallet ID
An example of the request:
The prefix is 888888_ in following sample request.
/v1/sofa/wallets/68451/sender/transactions/88888_1/cancel
The HTTP 200 means the withdrawal request has been cancelled successfully.
HTTP Code | Error Code | Error | Message | Description |
---|---|---|---|---|
403 | - | Forbidden. Invalid ID | - | No wallet ID found |
403 | - | Forbidden. Header not found | - | Missing X-API-CODE , X-CHECKSUM header or query param t |
403 | - | Forbidden. Invalid timestamp | - | The timestamp t is not in the valid time range |
403 | - | Forbidden. Invalid checksum | - | The request is considered a replay request |
403 | - | Forbidden. Invalid API code | - | X-API-CODE header contains invalid API code |
403 | - | Invalid API code for wallet {WALLET_ID} | - | The API code mismatched |
403 | - | Forbidden. Checksum unmatch | - | X-CHECKSUM header contains wrong checksum |
403 | - | Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) | - | Send requests too frequently |
403 | 177 | Illegal state | - | The {ORDER_ID} withdrawal request is not in Init or Failed state |
403 | 385 | API Secret not valid | - | Invalid API code permission |
404 | 304 | Wallet ID invalid | - | The {ORDER_ID} not found |
Check the latest withdrawal transaction state of certain order ID.
The order ID is used in the withdraw assets API.
VIEW
GET /v1/sofa/wallets/WALLET_ID
/sender/transactions/ORDER_ID
WALLET_ID
must be a withdrawal wallet ID
An example of the request:
The prefix is 888888_ in following sample request.
/v1/sofa/wallets/68451/sender/transactions/888888_1
An example of a successful response:
{
"order_id": "888888_1",
"address": "0xaa0cA2f9bA3A33a915a27e289C9719adB2ad7d73",
"amount": "1.11",
"memo": "",
"in_chain_block": 1016603,
"txid": "db0f3a27de564a411aeff1d2cb3234c54817de1ecc2258a510a50c5a1063d41c",
"create_time": "2020-03-16T10:27:57Z"
}
The response includes the following parameters:
Field | Type | Description |
---|---|---|
order_id | string | The unique ID specified in sender/transactions API |
address | string | Outgoing address |
amount | string | Withdrawal amount |
memo | string | Memo on blockchain |
in_chain_block | int64 | The block that contains this transaction |
txid | string | Transaction ID |
create_time | string | The withdrawal time in UTC |
HTTP Code | Error Code | Error | Message | Description |
---|---|---|---|---|
403 | - | Forbidden. Invalid ID | - | No wallet ID found |
403 | - | Forbidden. Header not found | - | Missing X-API-CODE , X-CHECKSUM header or query param t |
403 | - | Forbidden. Invalid timestamp | - | The timestamp t is not in the valid time range |
403 | - | Forbidden. Invalid checksum | - | The request is considered a replay request |
403 | - | Forbidden. Invalid API code | - | X-API-CODE header contains invalid API code |
403 | - | Invalid API code for wallet {WALLET_ID} | - | The API code mismatched |
403 | - | Forbidden. Checksum unmatch | - | X-CHECKSUM header contains wrong checksum |
403 | - | Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) | - | Send requests too frequently |
403 | 385 | API Secret not valid | - | Invalid API code permission |
404 | 304 | Wallet ID invalid | - | The {ORDER_ID} not found |
Check the all withdrawal transaction states of certain order ID.
The order ID is used in the withdraw assets API.
VIEW
GET /v1/sofa/wallets/WALLET_ID
/sender/transactions/ORDER_ID
/all
WALLET_ID
must be a withdrawal wallet ID
An example of the request:
The prefix is 888888_ in following sample request.
/v1/sofa/wallets/68451/sender/transactions/888888_1/all
An example of a successful response:
The sample shows the states of a resent transaction
{
"transactions": [
{
"address": "0x36a49c68EF1e3f39CDbaE2f5636C74BA10815cea",
"amount": "0.105",
"create_time": "2020-09-24T03:43:17Z",
"in_chain_block": 0,
"memo": "",
"order_id": "888888_1",
"state": 6,
"txid": "0x2a8a44f1cfed9cd7b86d86170e2418566765f88c5186246f571374df218fd1a1"
},
{
"address": "0x36a49c68EF1e3f39CDbaE2f5636C74BA10815cea",
"amount": "0.105",
"create_time": "2020-09-24T03:44:35Z",
"in_chain_block": 8742982,
"memo": "",
"order_id": "888888_1",
"state": 4,
"txid": "0xfbeaae4b87f977bcce8ef44672e035d287b96be24e779757c1a7f598501881ef"
}
]
}
The response includes the following parameters:
Field | Type | Description |
---|---|---|
order_id | string | The unique ID specified in sender/transactions API |
address | string | Outgoing address |
amount | string | Withdrawal amount |
memo | string | Memo on blockchain |
in_chain_block | int64 | The block that contains this transaction |
txid | string | Transaction ID |
create_time | string | The withdrawal time in UTC |
state | int | Refer to Transaction State Definition |
HTTP Code | Error Code | Error | Message | Description |
---|---|---|---|---|
403 | - | Forbidden. Invalid ID | - | No wallet ID found |
403 | - | Forbidden. Header not found | - | Missing X-API-CODE , X-CHECKSUM header or query param t |
403 | - | Forbidden. Invalid timestamp | - | The timestamp t is not in the valid time range |
403 | - | Forbidden. Invalid checksum | - | The request is considered a replay request |
403 | - | Forbidden. Invalid API code | - | X-API-CODE header contains invalid API code |
403 | - | Invalid API code for wallet {WALLET_ID} | - | The API code mismatched |
403 | - | Forbidden. Checksum unmatch | - | X-CHECKSUM header contains wrong checksum |
403 | - | Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) | - | Send requests too frequently |
403 | 385 | API Secret not valid | - | Invalid API code permission |
404 | 304 | Wallet ID invalid | - | The {ORDER_ID} not found |
Query event logs of a withdrawal transaction by transaction hash.
VIEW
GET /v1/sofa/wallets/WALLET_ID
/sender/transactions/eventlog?txid=TXID
WALLET_ID
should be a withdrawal wallet ID
An example of the request:
/v1/sofa/wallets/345312/sender/transactions/eventlog?txid=0xe82f0be9b30d840eca64e28e6f7562b7352b3b54519a7e63fb8f6d4609194bb9
The request includes the following parameters:
Field | Type | Note | Description |
---|---|---|---|
txid | string | required | Representing the transaction hash to query the event log |
An example of a successful response:
{
"logs": [
{
"address": "0xeCb258697e1A4B1fE11A43fC93bD4907f1EC8c04",
"block_hash": "0x37b6b94b8fac1eb810ddda89ceedabd37f1017f671fe41a245dc6558a25cb4bf",
"block_number": 11173598,
"data": "000000000000000000000000000000000000000000000000000000003b9aca00",
"index": 0,
"removed": false,
"topics": [
"0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
"0x000000000000000000000000a952d7fc7965bec3cb03c79084236534ee2ab3cd",
"0x000000000000000000000000d5909bacfc1fad78e4e45e9e2fef8b4e61c8fd0d"
],
"tx_hash": "0xe82f0be9b30d840eca64e28e6f7562b7352b3b54519a7e63fb8f6d4609194bb9",
"tx_index": 0
}
]
}
The response includes the following parameters:
Field | Type | Description |
---|---|---|
logs | array | The event logs |
address | string | From which this event originated from |
block_hash | string | Hash of the block where this transaction was in |
block_number | uint64 | Block number where this transaction was in |
data | string | The data containing non-indexed log parameter |
index | uint | Integer of the event index position in the block |
removed | boolean | Indicate the log is removed (due to chain reorg) |
topics | array | An array of values which must each appear in the log entries |
tx_hash | string | Hash of the transaction |
tx_index | uint | Integer of the transactions index position in the block |
HTTP Code | Error Code | Error | Message | Description |
---|---|---|---|---|
403 | - | Forbidden. Invalid ID | - | No wallet ID found |
403 | - | Forbidden. Header not found | - | Missing X-API-CODE , X-CHECKSUM header or query param t |
403 | - | Forbidden. Invalid timestamp | - | The timestamp t is not in the valid time range |
403 | - | Forbidden. Invalid checksum | - | The request is considered a replay request |
403 | - | Forbidden. Invalid API code | - | X-API-CODE header contains invalid API code |
403 | - | Invalid API code for wallet {WALLET_ID} | - | The API code mismatched |
403 | - | Forbidden. Checksum unmatch | - | X-CHECKSUM header contains wrong checksum |
403 | - | Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) | - | Send requests too frequently |
403 | 385 | API Secret not valid | - | Invalid API code permission |
400 | 112 | Invalid parameter | - | Missing necessary parameters |
400 | 112 | Invalid parameter | {TXID} not found | No relevant withdrawal request to TXID |
400 | 112 | Invalid parameter | {TXID} not in blockchain | Only in-chain withdrawal transactions allowed to query event log |
400 | 303 | Invalid currency | - | Not supported cryptocurrency to query event log |
Get the withdrawal wallet balance. Facilitate to establish a real-time balance monitoring mechanism.
VIEW
GET /v1/sofa/wallets/WALLET_ID
/sender/balance
WALLET_ID
must be a withdrawal wallet ID
An example of the request:
/v1/sofa/wallets/632543/sender/balance
An example of a successful response:
{
"currency": 60,
"wallet_address": "0xaa0cA2f9bA3A33a915a27e289C9719adB2ad7d73",
"token_address": "",
"balance": "0.619673333517576",
"token_balance": "",
"unconfirm_balance": "0",
"unconfirm_token_balance": ""
}
The response includes the following parameters:
Field | Type | Description |
---|---|---|
currency | int64 | Registered coin types. Refer to Currency Definition |
wallet_address | string | Wallet address |
token_address | string | Token contract address |
balance | string | Withdrawal wallet balance |
token_balance | string | Withdrawal wallet token balance |
unconfirm_balance | string | Unconfirmed withdrawal wallet balance |
unconfirm_token_balance | string | Unconfirmed withdrawal wallet token balance |
err_reason | string | Error message if fail to get balance |
The currencies that support the unconfirmed balance are BTC, LTC, ETH, BCH, BSV, DASH
HTTP Code | Error Code | Error | Message | Description |
---|---|---|---|---|
403 | - | Forbidden. Invalid ID | - | No wallet ID found |
403 | - | Forbidden. Header not found | - | Missing X-API-CODE , X-CHECKSUM header or query param t |
403 | - | Forbidden. Invalid timestamp | - | The timestamp t is not in the valid time range |
403 | - | Forbidden. Invalid checksum | - | The request is considered a replay request |
403 | - | Forbidden. Invalid API code | - | X-API-CODE header contains invalid API code |
403 | - | Invalid API code for wallet {WALLET_ID} | - | The API code mismatched |
403 | - | Forbidden. Checksum unmatch | - | X-CHECKSUM header contains wrong checksum |
403 | - | Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) | - | Send requests too frequently |
403 | 385 | API Secret not valid | - | Invalid API code permission |
404 | 304 | Wallet ID invalid | - | The wallet is not allowed to perform this request |
Query the detailed information of the withdrawal callback by the order ID.
This API only provides in-chain transactions query, for those not in-chain transactions use Query All Withdrawal Transaction States API instead.
VIEW
GET /v1/sofa/wallets/WALLET_ID
/sender/notifications/order_id/ORDER_ID
An example of the request:
The prefix is 888888_ in following sample request.
/v1/sofa/wallets/68451/sender/notifications/order_id/888888_1
An example of a successful response:
{
"notification": {
"addon": {},
"amount": "100000000000000",
"block_height": 7813953,
"broadcast_at": 1588211126,
"chain_at": 1588211126,
"confirm_blocks": 109490,
"currency": "ETH",
"fees": "21000000000000",
"from_address": "0xaa0cA2f9bA3A33a915a27e289C9719adB2ad7d73",
"memo": "",
"order_id": "888888_1",
"processing_state": 2,
"serial": 90000000554,
"state": 3,
"tindex": 30,
"to_address": "0x60589A749AAC632e9A830c8aBE042D1899d8Dd15",
"txid": "0x471c11f139ce1a7e0627a05cea50d64e47e797c94fd72025f1978cc919e07aa9",
"type": 2,
"vout_index": 0,
"wallet_id": 68451
}
}
The response includes the following parameters:
Field | Type | Description |
---|---|---|
notification | object | Refer to Callback Definition |
HTTP Code | Error Code | Error | Message | Description |
---|---|---|---|---|
403 | - | Forbidden. Invalid ID | - | No wallet ID found |
403 | - | Forbidden. Header not found | - | Missing X-API-CODE , X-CHECKSUM header or query param t |
403 | - | Forbidden. Invalid timestamp | - | The timestamp t is not in the valid time range |
403 | - | Forbidden. Invalid checksum | - | The request is considered a replay request |
403 | - | Forbidden. Invalid API code | - | X-API-CODE header contains invalid API code |
403 | - | Invalid API code for wallet {WALLET_ID} | - | The API code mismatched |
403 | - | Forbidden. Checksum unmatch | - | X-CHECKSUM header contains wrong checksum |
403 | - | Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) | - | Send requests too frequently |
403 | 385 | API Secret not valid | - | Invalid API code permission |
404 | 304 | Wallet ID invalid | - | The wallet is not allowed to perform this request or the {ORDER_ID} is not found |
Set an authorized IP to the withdrawal request ACL dynamically.
If a static ACL has been set in web control panel, the API will fail.
POST /v1/sofa/wallets/WALLET_ID
/sender/transactions/acl
An example of the request:
/v1/sofa/wallets/632543/sender/transactions/acl
{
"acl": "192.168.101.55"
}
The request includes the following parameters:
Field | Type | Note | Description |
---|---|---|---|
acl | string | requried | Specify an authorized IP in IPv4 format |
An example of a successful response:
{
"result": 1
}
The response includes the following parameters:
Field | Type | Description |
---|---|---|
result | int | Specify a successful API call |
HTTP Code | Error Code | Error | Message | Description |
---|---|---|---|---|
403 | - | Forbidden. Invalid ID | - | No wallet ID found |
403 | - | Forbidden. Header not found | - | Missing X-API-CODE , X-CHECKSUM header or query param t |
403 | - | Forbidden. Invalid timestamp | - | The timestamp t is not in the valid time range |
403 | - | Forbidden. Invalid checksum | - | The request is considered a replay request |
403 | - | Forbidden. Invalid API code | - | X-API-CODE header contains invalid API code |
403 | - | Invalid API code for wallet {WALLET_ID} | - | The API code mismatched |
403 | - | Forbidden. Checksum unmatch | - | X-CHECKSUM header contains wrong checksum |
403 | - | Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) | - | Send requests too frequently |
403 | 385 | API Secret not valid | - | Invalid API code permission |
404 | 304 | Wallet ID invalid | - | The wallet is invalid to perform this API call |
400 | 180 | Invalid format | - | The acl field is empty or does not conform to the IPv4 format |
400 | 180 | Operation failed | ACL has been set via web | The static ACL is not empty |
The callback handler can call this API to resend pending, risk-controlled or failed withdrawal callbacks.
Refer to Callback Integration for callback rules.
The resend operation could be requested on the web control panel as well.
POST /v1/sofa/wallets/WALLET_ID
/sender/notifications/manual
WALLET_ID
must be a withdrawal wallet ID
An example of the request:
/v1/sofa/wallets/55743/sender/notifications/manual
{
"notification_id": 0
}
The request includes the following parameters:
Field | Type | Note | Description |
---|---|---|---|
notification_id | int64 | required, 0 means all | Specify callback ID to resend |
This ID equal to the serial field of callback data.
An example of a successful response:
{
"count": 3
}
The response includes the following parameters:
Field | Type | Description |
---|---|---|
count | int | Count of callbacks just resent |
HTTP Code | Error Code | Error | Message | Description |
---|---|---|---|---|
403 | - | Forbidden. Invalid ID | - | No wallet ID found |
403 | - | Forbidden. Header not found | - | Missing X-API-CODE , X-CHECKSUM header or query param t |
403 | - | Forbidden. Invalid timestamp | - | The timestamp t is not in the valid time range |
403 | - | Forbidden. Invalid checksum | - | The request is considered a replay request |
403 | - | Forbidden. Invalid API code | - | X-API-CODE header contains invalid API code |
403 | - | Invalid API code for wallet {WALLET_ID} | - | The API code mismatched |
403 | - | Forbidden. Checksum unmatch | - | X-CHECKSUM header contains wrong checksum |
403 | - | Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) | - | Send requests too frequently |
403 | 385 | API Secret not valid | - | Invalid API code permission |
400 | 112 | Invalid parameter | - | Malformatted post body |
404 | 304 | Wallet ID invalid | - | The wallet is not allowed to perform this request |
Query the whitelist configuration of the withdrawal wallet.
GET /v1/sofa/wallets/WALLET_ID
/sender/whitelist/config
WALLET_ID
must be a withdrawal wallet ID
An example of the request:
/v1/sofa/wallets/55743/sender/whitelist/config
An example of a successful response:
{
"effective_latency": 0,
"whitelist_check": true
}
The response includes the following parameters:
Field | Type | Description |
---|---|---|
effective_latency | int64 | The effective latency of the whitelist entry, 0 means the whitelist entry will take effect immediately. |
whitelist_check | boolean | Indicate whether the withdrawal wallet has enabled whitelist checking. |
HTTP Code | Error Code | Error | Message | Description |
---|---|---|---|---|
403 | - | Forbidden. Invalid ID | - | No wallet ID found |
403 | - | Forbidden. Header not found | - | Missing X-API-CODE , X-CHECKSUM header or query param t |
403 | - | Forbidden. Invalid timestamp | - | The timestamp t is not in the valid time range |
403 | - | Forbidden. Invalid checksum | - | The request is considered a replay request |
403 | - | Forbidden. Invalid API code | - | X-API-CODE header contains invalid API code |
403 | - | Invalid API code for wallet {WALLET_ID} | - | The API code mismatched |
403 | - | Forbidden. Checksum unmatch | - | X-CHECKSUM header contains wrong checksum |
403 | - | Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) | - | Send requests too frequently |
403 | 385 | API Secret not valid | - | Invalid API code permission |
404 | 304 | Wallet ID invalid | - | The wallet is not allowed to perform this request |
Add an outgoing address to the withdrawal wallet's whitelist.
POST /v1/sofa/wallets/WALLET_ID
/sender/whitelist
WALLET_ID
must be a withdrawal wallet ID
An example of the request:
/v1/sofa/wallets/55743/sender/whitelist
{
"items": [
{
"address": "GCIFMEYIEWSX3K6EOPMEJ3FHW5AAPD6NW76J7LPBRAKD4JZKTISKUPHJ",
"memo": "865314",
"user_id": "USER001"
}
]
}
The request includes the following parameters:
Field | Type | Note | Description |
---|---|---|---|
items | array | required | Specify the whitelist entries |
address | string | required | The outgoing address |
memo | string | optional | The memo of the outgoing address |
user_id | string | optional, max length 255 |
The custom user ID of the outgoing address |
An example of a successful response:
{
"added_items": [
{
"address": "GCIFMEYIEWSX3K6EOPMEJ3FHW5AAPD6NW76J7LPBRAKD4JZKTISKUPHJ",
"memo": "865314",
"user_id": "USER001"
}
]
}
The response includes the following parameters:
Field | Type | Description |
---|---|---|
added_items | array | Array of added whitelist entries |
HTTP Code | Error Code | Error | Message | Description |
---|---|---|---|---|
403 | - | Forbidden. Invalid ID | - | No wallet ID found |
403 | - | Forbidden. Header not found | - | Missing X-API-CODE , X-CHECKSUM header or query param t |
403 | - | Forbidden. Invalid timestamp | - | The timestamp t is not in the valid time range |
403 | - | Forbidden. Invalid checksum | - | The request is considered a replay request |
403 | - | Forbidden. Invalid API code | - | X-API-CODE header contains invalid API code |
403 | - | Invalid API code for wallet {WALLET_ID} | - | The API code mismatched |
403 | - | Forbidden. Checksum unmatch | - | X-CHECKSUM header contains wrong checksum |
403 | - | Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) | - | Send requests too frequently |
403 | 385 | API Secret not valid | - | Invalid API code permission |
400 | 112 | Invalid parameter | - | Malformatted post body |
400 | 703 | Operation failed | invalid address: {INVALID_ADDRESS} | The address format does not comply with the cryptocurrency specification |
400 | 703 | Operation failed | invalid user id: {INVALID_USER_ID} | The length of the user ID exceeds 255 characters |
400 | 703 | Operation failed | this wallet does not support memo | The cryptocurrency does not support memo |
400 | 945 | The max length of BNB memo is 256 chars | - | Reached the limit of the length of BNB memo |
400 | 946 | The max length of EOS memo is 128 chars | - | Reached the limit of the length of EOS memo |
400 | 947 | The max length of XRP destination tag is 20 chars | - | Reached the limit of the length of XRP destination tag |
400 | 948 | The max length of XLM memo is 20 chars | - | Reached the limit of the length of XLM memo |
400 | 818 | Destination Tag must be integer | - | Wrong XRP destination tag format |
404 | 304 | Wallet ID invalid | - | The wallet is not allowed to perform this request |
Remove an outgoing address from the withdrawal wallet's whitelist.
DELETE /v1/sofa/wallets/WALLET_ID
/sender/whitelist
WALLET_ID
must be a withdrawal wallet ID
Only the entries exactly matches all the fields will be removed.
An example of the request:
/v1/sofa/wallets/55743/sender/whitelist
{
"items": [
{
"address": "GCIFMEYIEWSX3K6EOPMEJ3FHW5AAPD6NW76J7LPBRAKD4JZKTISKUPHJ",
"memo": "865314",
"user_id": "USER001"
}
]
}
The request includes the following parameters:
Field | Type | Note | Description |
---|---|---|---|
items | array | required | Specify the whitelist entries |
address | string | required | The outgoing address |
memo | string | optional | The memo of the outgoing address |
user_id | string | optional | The custom user ID of the outgoing address |
An example of a successful response:
{
"removed_items": [
{
"address": "GCIFMEYIEWSX3K6EOPMEJ3FHW5AAPD6NW76J7LPBRAKD4JZKTISKUPHJ",
"memo": "865314",
"user_id": "USER001"
}
]
}
The response includes the following parameters:
Field | Type | Description |
---|---|---|
removed_items | array | Array of removed whitelist entries |
HTTP Code | Error Code | Error | Message | Description |
---|---|---|---|---|
403 | - | Forbidden. Invalid ID | - | No wallet ID found |
403 | - | Forbidden. Header not found | - | Missing X-API-CODE , X-CHECKSUM header or query param t |
403 | - | Forbidden. Invalid timestamp | - | The timestamp t is not in the valid time range |
403 | - | Forbidden. Invalid checksum | - | The request is considered a replay request |
403 | - | Forbidden. Invalid API code | - | X-API-CODE header contains invalid API code |
403 | - | Invalid API code for wallet {WALLET_ID} | - | The API code mismatched |
403 | - | Forbidden. Checksum unmatch | - | X-CHECKSUM header contains wrong checksum |
403 | - | Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) | - | Send requests too frequently |
403 | 385 | API Secret not valid | - | Invalid API code permission |
400 | 112 | Invalid parameter | - | Malformatted post body |
404 | 304 | Wallet ID invalid | - | The wallet is not allowed to perform this request |
Check the withdrawal whitelist entry status in the withdrawal whitelist.
VIEW
POST /v1/sofa/wallets/WALLET_ID
/sender/whitelist/check
WALLET_ID
must be a withdrawal wallet ID
An example of the request:
/v1/sofa/wallets/557432/sender/whitelist/check
{
"address": "GCIFMEYIEWSX3K6EOPMEJ3FHW5AAPD6NW76J7LPBRAKD4JZKTISKUPHJ",
"memo": "865314",
"user_id": "USER001"
}
The request includes the following parameters:
Field | Type | Note | Description |
---|---|---|---|
address | string | required | The inquiry whitelist entry address |
memo | string | optional | The memo of the whitelist entry |
user_id | string | optional | The custom user ID of the whitelist entry |
An example of a successful response:
{
"address": "0x79D6660b2aB1d37AD5D11C2ca2B3EBba7Efd13F6",
"create_time": "2020-12-30T13:09:39Z",
"effective": true,
"effective_time": "2020-12-30T13:09:39Z",
"memo": "",
"state": 1,
"update_time": "2020-12-30T13:09:39Z",
"user_id": "USER001"
}
The response includes the following parameters:
Field | Type | Description |
---|---|---|
address | string | The inquiry whitelist entry address |
create_time | string | The creation time in UTC |
effective | boolean | Indicate whether the whitelist entry has taken effect |
effective_time | string | The effective time in UTC |
memo | string | The memo of the whitelist entry |
state | int | 1 means the entry is active, 2 means the entry is removed |
update_time | string | Last modification time in UTC |
user_id | string | The custom user ID of the whitelist entry |
HTTP Code | Error Code | Error | Message | Description |
---|---|---|---|---|
403 | - | Forbidden. Invalid ID | - | No wallet ID found |
403 | - | Forbidden. Header not found | - | Missing X-API-CODE , X-CHECKSUM header or query param t |
403 | - | Forbidden. Invalid timestamp | - | The timestamp t is not in the valid time range |
403 | - | Forbidden. Invalid checksum | - | The request is considered a replay request |
403 | - | Forbidden. Invalid API code | - | X-API-CODE header contains invalid API code |
403 | - | Invalid API code for wallet {WALLET_ID} | - | The API code mismatched |
403 | - | Forbidden. Checksum unmatch | - | X-CHECKSUM header contains wrong checksum |
403 | - | Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) | - | Send requests too frequently |
403 | 385 | API Secret not valid | - | Invalid API code permission |
400 | 112 | Invalid parameter | - | Malformatted post body |
400 | 703 | Operation failed | not found | Cannot find the inquiry whitelist entry |
400 | 703 | Operation failed | invalid address: {INVALID_ADDRESS} | The address format does not comply with the cryptocurrency specification |
400 | 703 | Operation failed | invalid user id: {INVALID_USER_ID} | The length of the user ID exceeds 255 characters |
400 | 703 | Operation failed | this wallet does not support memo | The cryptocurrency does not support memo |
404 | 304 | Wallet ID invalid | - | The wallet is not allowed to perform this request |
Used to query some kind of callbacks within a time interval.
VIEW
GET /v1/sofa/wallets/WALLET_ID
/sender/whitelist?from_time=from
&to_time=to
&start_index=offset
&request_number=count
&state=state
An example of the request:
/v1/sofa/wallets/557432/sender/whitelist
The request includes the following parameters:
Field | Type | Note | Description |
---|---|---|---|
from_time | int64 | optional, default 0 |
Start date (unix time in UTC) |
to_time | int64 | optional, default current time |
End date (unix time in UTC) |
start_index | int64 | optional, default 0 |
The offset to the first entry |
request_number | int64 | optional, default 1000 , max 2000 |
The count to request |
state | int | optional, default -1 |
Use 1 to query the active entries and 2 to query the removed entries, -1 means all entries |
An example of a successful response:
{
"items": [
{
"address": "GCIFMEYIEWSX3K6EOPMEJ3FHW5AAPD6NW76J7LPBRAKD4JZKTISKUPHJ",
"create_time": "2020-12-30T06:02:25Z",
"effective": false,
"effective_time": "2020-12-30T13:27:37Z",
"memo": "",
"state": 1,
"update_time": "2020-12-30T06:02:25Z",
"user_id": "USER001"
},
],
"total_count": 1
}
The response includes the following parameters:
Field | Type | Description |
---|---|---|
items | array | Arrary of the whitelist entries |
address | string | The whitelist entry address |
create_time | string | The creation time in UTC |
effective | boolean | Indicate whether the whitelist entry has taken effect |
effective_time | string | The effective time in UTC |
memo | string | The memo of the whitelist entry |
state | int | 1 means the entry is active, 2 means the entry is removed |
update_time | string | Last modification time in UTC |
user_id | string | The custom user ID of the whitelist entry |
HTTP Code | Error Code | Error | Message | Description |
---|---|---|---|---|
403 | - | Forbidden. Invalid ID | - | No wallet ID found |
403 | - | Forbidden. Header not found | - | Missing X-API-CODE , X-CHECKSUM header or query param t |
403 | - | Forbidden. Invalid timestamp | - | The timestamp t is not in the valid time range |
403 | - | Forbidden. Invalid checksum | - | The request is considered a replay request |
403 | - | Forbidden. Invalid API code | - | X-API-CODE header contains invalid API code |
403 | - | Invalid API code for wallet {WALLET_ID} | - | The API code mismatched |
403 | - | Forbidden. Checksum unmatch | - | X-CHECKSUM header contains wrong checksum |
403 | - | Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) | - | Send requests too frequently |
403 | 385 | API Secret not valid | - | Invalid API code permission |
404 | 304 | Wallet ID invalid | - | The wallet is not allowed to perform this request |
Get transaction history of withdrawal wallets.
VIEW
GET /v1/sofa/wallets/WALLET_ID
/sender/transactions?from_time=from
&to_time=to
&start_index=start
&request_number=count
WALLET_ID
should be a withdrawal wallet ID
An example of the request:
/v1/sofa/wallets/345312/sender/transactions?from_time=1559664000&to_time=1562255999&start_index=0&request_number=10
The request includes the following parameters:
Field | Type | Note | Description |
---|---|---|---|
from_time | int64 | optional, default 0 |
Start date (unix time in UTC) |
to_time | int64 | optional, default current time |
End date (unix time in UTC) |
start_index | int | optional, default 0 |
Index of starting transaction record |
request_number | int | optional, default 10 , max 500 |
Count of returning transaction record |
An example of a successful response:
{
"total_count": 169,
"transactions": [
{
"amount": "0.1",
"block_height": 10813730,
"block_time": "2021-08-11T06:13:01Z",
"blocklist_tags": [],
"fee": "0.000693",
"from_address": "0xaa0cA2f9bA3A33a915a27e289C9719adB2ad7d73",
"memo": "",
"out": true,
"source": "",
"state": 1,
"to_address": "0x79D6660b2aB1d37AD5D11C2ca2B3EBba7Efd13F6",
"txid": "0xe3607325e3b7c0190089d1fb41ce9fa059858c6b2e5dd220e55ba46707fc38f0"
},
{
"amount": "1",
"block_height": 10811102,
"block_time": "2021-08-10T17:24:21Z",
"blocklist_tags": [],
"fee": "0.000021",
"from_address": "0xaa0cA2f9bA3A33a915a27e289C9719adB2ad7d73",
"memo": "",
"out": true,
"source": "withdraw-api",
"state": 1,
"to_address": "0x8382Cc1B05649AfBe179e341179fa869C2A9862b",
"txid": "0x19657382aa16520c32eef0dacc0f16d78e9105e83d37d126b4f6687c0d651859"
},
]
}
The response includes the following parameters:
Field | Type | Description |
---|---|---|
total_count | int | Total transactions in specified date duration |
transactions | array | Array of transaction record |
txid | string | Transaction ID |
from_address | string | Sender address of the transaction |
to_address | string | Recipient address of the transaction |
out | boolean | True means outgoing transaction |
amount | string | Transaction amount |
blocklist_tags | array | The tags of CYBAVO AML detection. If out is true, the to_address is tagged. Otherwise, the from_address is tagged |
block_height | int64 | The block height |
block_time | time | When was the transaction packed into block (in chain) in UTC time |
fee | string | Transaction blockchain fee |
memo | string | Memo of the transaction |
source | string | withdraw-api means that the transaction was triggered by the withdrawal API, otherwise it was triggered from the web withdrawal UI |
state | int | Refer to State Definition bellow |
ID | Description |
---|---|
1 | Success, the transaction status is successful |
2 | Failed, the transaction status is failed |
3 | Invalid, the transaction status is successful but is identified as invalid by the SOFA system |
HTTP Code | Error Code | Error | Message | Description |
---|---|---|---|---|
403 | - | Forbidden. Invalid ID | - | No wallet ID found |
403 | - | Forbidden. Header not found | - | Missing X-API-CODE , X-CHECKSUM header or query param t |
403 | - | Forbidden. Invalid timestamp | - | The timestamp t is not in the valid time range |
403 | - | Forbidden. Invalid checksum | - | The request is considered a replay request |
403 | - | Forbidden. Invalid API code | - | X-API-CODE header contains invalid API code |
403 | - | Invalid API code for wallet {WALLET_ID} | - | The API code mismatched |
403 | - | Forbidden. Checksum unmatch | - | X-CHECKSUM header contains wrong checksum |
403 | - | Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) | - | Send requests too frequently |
403 | 385 | API Secret not valid | - | Invalid API code permission |
400 | 112 | Invalid parameter | - | from_time or to_time is invalid |
Sign message, equivalent to eth_sign
.
VIEW
POST /v1/sofa/wallets/WALLET_ID
/signmessage
WALLET_ID
must be a withdrawal wallet ID
An example of the request:
/v1/sofa/wallets/557432/signmessage
{
"message": "This is proof that I, user A, have access to this address."
}
The request includes the following parameters:
Field | Type | Note | Description |
---|---|---|---|
message | string | required | Message to be signed |
An example of a successful response:
{
"signed_message": "0xf296a678ce1d577acbee25119b7be821db70e960d6e65ef73fb1e50fa832759d27d35df2dd309be07cb5a9b9f6c87f5eeae11ff56b995e0b32d6288b1039555b2a"
}
The response includes the following parameters:
Field | Type | Description |
---|---|---|
signed_message | string | Signed message |
HTTP Code | Error Code | Error | Message | Description |
---|---|---|---|---|
403 | - | Forbidden. Invalid ID | - | No wallet ID found |
403 | - | Forbidden. Header not found | - | Missing X-API-CODE , X-CHECKSUM header or query param t |
403 | - | Forbidden. Invalid timestamp | - | The timestamp t is not in the valid time range |
403 | - | Forbidden. Invalid checksum | - | The request is considered a replay request |
403 | - | Forbidden. Invalid API code | - | X-API-CODE header contains invalid API code |
403 | - | Invalid API code for wallet {WALLET_ID} | - | The API code mismatched |
403 | - | Forbidden. Checksum unmatch | - | X-CHECKSUM header contains wrong checksum |
403 | - | Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) | - | Send requests too frequently |
403 | 385 | API Secret not valid | - | Invalid API code permission |
400 | 112 | Invalid parameter | - | Malformatted post body |
404 | 303 | Invalid currency | - | The wallet is not allowed to perform this request |
404 | 304 | Wallet ID invalid | mapped wallet not supported | - |
Executes a contract read ABI call.
VIEW
GET /v1/sofa/wallets/WALLET_ID
/contract/read?contract=contract_address
&data=data
WALLET_ID
should be a withdrawal wallet ID
An example of the request:
/v1/sofa/wallets/345312/contract/read?contract=0xad6d458402f60fd3bd25163575031acdce07538d&data=0xdd62ed3e000000000000000000000000d11bd6e308b8dc1c5243d54cf41a427ca0f46943000000000000000000000000e592427a0aece92de3edee1f18e0157c05861564
The request includes the following parameters:
Field | Type | Note | Description |
---|---|---|---|
contract | string | required | Representing the contract to interact with |
data | string | requried | The hash of the method signature and encoded parameters |
The
data
must be encoded by web3.eth.abi.encodeFunctionCall() of web3.js.
An example of a successful response:
{
"output": "ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff"
}
The response includes the following parameters:
Field | Type | Description |
---|---|---|
output | string | The output of read ABI call |
The
output
can be decoded by web3.eth.abi.decodeparameters() of web3.js.
HTTP Code | Error Code | Error | Message | Description |
---|---|---|---|---|
403 | - | Forbidden. Invalid ID | - | No wallet ID found |
403 | - | Forbidden. Header not found | - | Missing X-API-CODE , X-CHECKSUM header or query param t |
403 | - | Forbidden. Invalid timestamp | - | The timestamp t is not in the valid time range |
403 | - | Forbidden. Invalid checksum | - | The request is considered a replay request |
403 | - | Forbidden. Invalid API code | - | X-API-CODE header contains invalid API code |
403 | - | Invalid API code for wallet {WALLET_ID} | - | The API code mismatched |
403 | - | Forbidden. Checksum unmatch | - | X-CHECKSUM header contains wrong checksum |
403 | - | Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) | - | Send requests too frequently |
403 | 385 | API Secret not valid | - | Invalid API code permission |
404 | 304 | Wallet ID invalid | wrong wallet type | - |
404 | 304 | Wallet ID invalid | archived wallet | - |
404 | 304 | Wallet ID invalid | mapped wallet not supported | - |
400 | 112 | Invalid parameter | - | Missing necessary parameters |
400 | 112 | Operation failed | invalid address: {contract_address} | The contract address does not conform to the cryptocurrency format |
400 | 112 | Invalid parameter | no contract policy | There is no contract policy of the given wallet |
400 | 112 | Invalid parameter | unsupported contract | There is no contract policy of the given contract address |
400 | 303 | Invalid currency | - | Not supported cryptocurrency to call contract read ABI |
Used to query some kind of callbacks within a time interval.
VIEW
GET /v1/sofa/wallets/WALLET_ID
/notifications?from_time=from
&to_time=to
&type=type
An example of the request:
/v1/sofa/wallets/677414/notifications?from_time=1561651200&to_time=1562255999&type=2
The request includes the following parameters:
Field | Type | Note | Description |
---|---|---|---|
from_time | int64 | optional, default 0 |
Start date (unix time in UTC) |
to_time | int64 | optional, default current time |
End date (unix time in UTC) |
type | int | optional, default -1 |
Refer to Callback Type |
An example of a successful response:
{
"notifications": [
{
"type": 2,
"serial": 90000000003,
"order_id": "a206",
"currency": "BNB",
"txid": "76B8B2B1E25472FFE7B8FCE85742E0964FEDB1B679DE963FA19F430E8B287F93",
"block_height": 25844472,
"tindex": 2,
"vout_index": 0,
"amount": "15000000",
"fees": "37500",
"memo": "CC",
"broadcast_at": 0,
"chain_at": 1562234190,
"from_address": "tbnb1f805kv6z8nq2whrcnkagjte3jjss2sxf2rfls0",
"to_address": "tbnb1655kasahedvaeudaeq6jggr7kal8qgwygu9xqk",
"wallet_id": 677414,
"state": 3,
"confirm_blocks": 1,
"processing_state": 1,
"addon": {}
}
]
}
The response includes the following parameters:
Field | Type | Description |
---|---|---|
notifications | array | Arrary of callbacks, refer to Callback Definition |
HTTP Code | Error Code | Error | Message | Description |
---|---|---|---|---|
403 | - | Forbidden. Invalid ID | - | No wallet ID found |
403 | - | Forbidden. Header not found | - | Missing X-API-CODE , X-CHECKSUM header or query param t |
403 | - | Forbidden. Invalid timestamp | - | The timestamp t is not in the valid time range |
403 | - | Forbidden. Invalid checksum | - | The request is considered a replay request |
403 | - | Forbidden. Invalid API code | - | X-API-CODE header contains invalid API code |
403 | - | Invalid API code for wallet {WALLET_ID} | - | The API code mismatched |
403 | - | Forbidden. Checksum unmatch | - | X-CHECKSUM header contains wrong checksum |
403 | - | Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) | - | Send requests too frequently |
403 | 385 | API Secret not valid | - | Invalid API code permission |
Query the detailed information of the callback by its serial ID. It can be used to reconfirm whether a deposit callback exists.
VIEW
POST /v1/sofa/wallets/WALLET_ID
/notifications/get_by_id
An example of the request:
/v1/sofa/wallets/677414/notifications/get_by_id
{
"ids": [
90000000140,
90000000139
]
}
The request includes the following parameters:
Field | Type | Note | Description |
---|---|---|---|
ids | array | requried | Specify the IDs for query |
An example of a successful response:
{
"notifications": [
{
"type": 3,
"serial": 90000000139,
"order_id": "",
"currency": "ADA",
"txid": "35c283a6f13f5886240fe2e815bc149154ec066cd2061202318dd4e4bf8af35e",
"block_height": 1003304,
"tindex": 0,
"vout_index": 0,
"amount": "24447",
"fees": "0",
"memo": "",
"broadcast_at": 1584088556,
"chain_at": 1584088556,
"from_address": "",
"to_address": "37btjrVyb4KG8gKeZjJguinwdsbcRV65ngHhBUaJWf36QxiakTV3UHiNUP9arReXMZQnpRBVVdkcBB4GyiWzPRSTmg41mTzMpxgfhtfRHtaBCKJNbX",
"wallet_id": 677414,
"state": 3,
"confirm_blocks": 2,
"processing_state": 1,
"addon": {}
},
{
"type": 3,
"serial": 90000000140,
"order_id": "",
"currency": "ADA",
"txid": "fa120b6283509f0ab2b136a3ac8b613aa3ca2f36ce7c2744e122668d013cfdb5",
"block_height": 1003305,
"tindex": 0,
"vout_index": 0,
"amount": "55497180",
"fees": "0",
"memo": "",
"broadcast_at": 1584088576,
"chain_at": 1584088576,
"from_address": "",
"to_address": "37btjrVyb4KDKCyAPRUPxpGiUPWunpBAkGRX8U3h7LYzS2UrHUnEQozcCyqR2GfBVnM3frTaUNEb8DoNGo9JakrskAtaWt6vED6R6ohkmaJ2qr4oCg",
"wallet_id": 677414,
"state": 3,
"confirm_blocks": 1,
"processing_state": 1,
"addon": {}
}
]
}
The response includes the following parameters:
Field | Type | Description |
---|---|---|
notifications | array | Arrary of callbacks, refer to Callback Definition |
HTTP Code | Error Code | Error | Message | Description |
---|---|---|---|---|
403 | - | Forbidden. Invalid ID | - | No wallet ID found |
403 | - | Forbidden. Header not found | - | Missing X-API-CODE , X-CHECKSUM header or query param t |
403 | - | Forbidden. Invalid timestamp | - | The timestamp t is not in the valid time range |
403 | - | Forbidden. Invalid checksum | - | The request is considered a replay request |
403 | - | Forbidden. Invalid API code | - | X-API-CODE header contains invalid API code |
403 | - | Invalid API code for wallet {WALLET_ID} | - | The API code mismatched |
403 | - | Forbidden. Checksum unmatch | - | X-CHECKSUM header contains wrong checksum |
403 | - | Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) | - | Send requests too frequently |
403 | 385 | API Secret not valid | - | Invalid API code permission |
Get the blockchain synchronization status of a wallet.
VIEW
GET /v1/sofa/wallets/WALLET_ID
/blocks
An example of the request:
/v1/sofa/wallets/677414/blocks
An example of a successful response:
{
"latest_block_height": 29317651,
"synced_block_height": 28529203
}
The response includes the following parameters:
Field | Type | Description |
---|---|---|
latest_block_height | int64 | The latest block height on blockchain |
synced_block_height | int64 | The current synced block height |
HTTP Code | Error Code | Error | Message | Description |
---|---|---|---|---|
403 | - | Forbidden. Invalid ID | - | No wallet ID found |
403 | - | Forbidden. Header not found | - | Missing X-API-CODE , X-CHECKSUM header or query param t |
403 | - | Forbidden. Invalid timestamp | - | The timestamp t is not in the valid time range |
403 | - | Forbidden. Invalid checksum | - | The request is considered a replay request |
403 | - | Forbidden. Invalid API code | - | X-API-CODE header contains invalid API code |
403 | - | Invalid API code for wallet {WALLET_ID} | - | The API code mismatched |
403 | - | Forbidden. Checksum unmatch | - | X-CHECKSUM header contains wrong checksum |
403 | - | Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) | - | Send requests too frequently |
403 | 385 | API Secret not valid | - | Invalid API code permission |
Query average blockchain fee within latest N blocks.
VIEW
POST /v1/sofa/wallets/WALLET_ID
/autofee
An example of the request:
/v1/sofa/wallets/635718/autofee
{
"block_num": 1
}
The request includes the following parameters:
Field | Type | Note | Description |
---|---|---|---|
block_num | int | optional, default 1 , range 1~100 |
Query the average blockchain fee in the last N blocks |
An example of a successful response:
{
"auto_fee": "1"
}
The response includes the following parameters:
Field | Type | Description |
---|---|---|
auto_fee | string | Mining fee denominated in the smallest cryptocurrency unit |
HTTP Code | Error Code | Error | Message | Description |
---|---|---|---|---|
403 | - | Forbidden. Invalid ID | - | No wallet ID found |
403 | - | Forbidden. Header not found | - | Missing X-API-CODE , X-CHECKSUM header or query param t |
403 | - | Forbidden. Invalid timestamp | - | The timestamp t is not in the valid time range |
403 | - | Forbidden. Invalid checksum | - | The request is considered a replay request |
403 | - | Forbidden. Invalid API code | - | X-API-CODE header contains invalid API code |
403 | - | Invalid API code for wallet {WALLET_ID} | - | The API code mismatched |
403 | - | Forbidden. Checksum unmatch | - | X-CHECKSUM header contains wrong checksum |
403 | - | Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) | - | Send requests too frequently |
403 | 385 | API Secret not valid | - | Invalid API code permission |
400 | 112 | Invalid parameter | - | The block_num is out of range |
Batch Query average blockchain fee within latest N blocks.
VIEW
POST /v1/sofa/wallets/WALLET_ID
/autofees
An example of the request:
/v1/sofa/wallets/854714/autofees
{
"block_nums": [
1,
5,
10
]
}
The request includes the following parameters:
Field | Type | Note | Description |
---|---|---|---|
block_nums | array | required, max 5 entries, each entry is range 1~100 |
Batch query the average blockchain fee in the last N blocks |
An example of a successful response:
{
"auto_fees": [
{
"auto_fee": "49000000000",
"block_num": 1
},
{
"auto_fee": "49000000000",
"block_num": 5
},
{
"auto_fee": "38000000000",
"block_num": 10
}
]
}
The response includes the following parameters:
Field | Type | Description |
---|---|---|
auto_fees | array | Result of the inquiry |
block_num | int | Inquiry block number |
auto_fee | string | Mining fee denominated in the smallest cryptocurrency unit |
HTTP Code | Error Code | Error | Message | Description |
---|---|---|---|---|
403 | - | Forbidden. Invalid ID | - | No wallet ID found |
403 | - | Forbidden. Header not found | - | Missing X-API-CODE , X-CHECKSUM header or query param t |
403 | - | Forbidden. Invalid timestamp | - | The timestamp t is not in the valid time range |
403 | - | Forbidden. Invalid checksum | - | The request is considered a replay request |
403 | - | Forbidden. Invalid API code | - | X-API-CODE header contains invalid API code |
403 | - | Invalid API code for wallet {WALLET_ID} | - | The API code mismatched |
403 | - | Forbidden. Checksum unmatch | - | X-CHECKSUM header contains wrong checksum |
403 | - | Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) | - | Send requests too frequently |
403 | 385 | API Secret not valid | - | Invalid API code permission |
400 | 112 | Invalid parameter | - | Exceeds 5 entries or each entry not in range |
Get transaction history of vault wallets.
VIEW
GET /v1/sofa/wallets/WALLET_ID
/transactions?from_time=from
&to_time=to
&start_index=start
&request_number=count
&state=state
WALLET_ID
should be a vault wallet ID
An example of the request:
/v1/sofa/wallets/488471/transactions?from_time=1559664000&to_time=1562255999&start_index=0&request_number=1
The request includes the following parameters:
Field | Type | Note | Description |
---|---|---|---|
from_time | int64 | optional, default 0 |
Start date (unix time in UTC) |
to_time | int64 | optional, default current time |
End date (unix time in UTC) |
start_index | int | optional, default 0 |
Index of starting transaction record |
request_number | int | optional, default 1000 , max 5000 |
Count of returning transaction record |
state | int | optional, default -1 |
Refer to Transaction State Filter Definition bellow |
ID | Description |
---|---|
0 | WaitApproval |
1 | Rejected |
2 | Approved |
3 | Failed |
4 | NextLevel |
5 | Cancelled |
6 | BatchDone |
-1 | All states (for inquiry) |
An example of a successful response:
{
"transaction_count": 3,
"transaction_item": [
{
"issue_user_id": 3,
"issue_user_name": "wallet owner (user@gmail.com)",
"description": "TO SND",
"wallet_id": 488471,
"wallet_name": "BNB I",
"wallet_address": "tbnb1655kasahedvaeudaeq6jggr7kal8qgwygu9xqk",
"token_address": "",
"txid": "3E6D61D1D39FA5DD3B86C2C28FFAD3D98CD7AFDB62346468D3C4FFE710CAAF85",
"currency": 714,
"currency_name": "BNB",
"outgoing_address": "tbnb1f805kv6z8nq2whrcnkagjte3jjss2sxf2rfls0",
"outgoing_address_name": "BNB SND",
"amount": "2",
"fee": "0",
"txno": 100087,
"approval_item": [
{
"approval_id": 3,
"approval_user": "wallet owner (user@gmail.com)",
"approval_time": 1562210142,
"user_message": "",
"level": 0,
"owner": 1,
"confirm": 1,
"state": 2,
"error_code": 0
}
],
"state": 2,
"create_time": 1562210129,
"transaction_time": 1562210142,
"scheduled_name": "",
"transaction_type": 0,
"eos_transaction_type": 0,
"real_amount": "2",
"chain_fee": "0.000375",
"platform_fee": "0",
"tx_category": "",
"memo": "TO SND"
}
]
}
The response includes the following parameters:
Field | Type | Description |
---|---|---|
transaction_count | int | Total transactions in specified date duration |
transaction_item | array | Array of transaction record |
Refer to Currency Definition or here for more detailed currency definitions
HTTP Code | Error Code | Error | Message | Description |
---|---|---|---|---|
403 | - | Forbidden. Invalid ID | - | No wallet ID found |
403 | - | Forbidden. Header not found | - | Missing X-API-CODE , X-CHECKSUM header or query param t |
403 | - | Forbidden. Invalid timestamp | - | The timestamp t is not in the valid time range |
403 | - | Forbidden. Invalid checksum | - | The request is considered a replay request |
403 | - | Forbidden. Invalid API code | - | X-API-CODE header contains invalid API code |
403 | - | Invalid API code for wallet {WALLET_ID} | - | The API code mismatched |
403 | - | Forbidden. Checksum unmatch | - | X-CHECKSUM header contains wrong checksum |
403 | - | Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) | - | Send requests too frequently |
403 | 385 | API Secret not valid | - | Invalid API code permission |
Get the vault wallet balance. Facilitate to establish a real-time balance monitoring mechanism.
VIEW
GET /v1/sofa/wallets/WALLET_ID
/vault/balance
WALLET_ID
must be a vault wallet ID
An example of the request:
/v1/sofa/wallets/488471/vault/balance
An example of a successful response:
BTC vault wallet
{
"balance": "0.00009798",
"currency": 0,
"token_address": "",
"token_balance": "",
"unconfirm_balance": "0",
"unconfirm_token_balance": "",
"wallet_address": "2Mw1iJnQvAt3hNEvEZKdHkij8TNtzjaF3LH"
}
USDT-Omni vault wallet that mapping to above BTC vault wallet
{
"balance": "0.00009798",
"currency": 0,
"token_address": "31",
"token_balance": "0.1",
"unconfirm_balance": "0",
"unconfirm_token_balance": "",
"wallet_address": "2Mw1iJnQvAt3hNEvEZKdHkij8TNtzjaF3LH"
}
The response includes the following parameters:
Field | Type | Description |
---|---|---|
currency | int64 | Registered coin types. Refer to Currency Definition |
wallet_address | string | Wallet address |
token_address | string | Token contract address |
balance | string | Withdrawal wallet balance |
token_balance | string | Withdrawal wallet token balance |
unconfirm_balance | string | Unconfirmed withdrawal wallet balance |
unconfirm_token_balance | string | Unconfirmed withdrawal wallet token balance |
The currencies that support the unconfirmed balance are BTC, LTC, ETH, BCH, BSV, DASH
HTTP Code | Error Code | Error | Message | Description |
---|---|---|---|---|
403 | - | Forbidden. Invalid ID | - | No wallet ID found |
403 | - | Forbidden. Header not found | - | Missing X-API-CODE , X-CHECKSUM header or query param t |
403 | - | Forbidden. Invalid timestamp | - | The timestamp t is not in the valid time range |
403 | - | Forbidden. Invalid checksum | - | The request is considered a replay request |
403 | - | Forbidden. Invalid API code | - | X-API-CODE header contains invalid API code |
403 | - | Invalid API code for wallet {WALLET_ID} | - | The API code mismatched |
403 | - | Forbidden. Checksum unmatch | - | X-CHECKSUM header contains wrong checksum |
403 | - | Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) | - | Send requests too frequently |
404 | 304 | Wallet ID invalid | - | The wallet is not allowed to perform this request |
403 | 385 | API Secret not valid | - | Invalid API code permission |
Activate the API code of a certain wallet. Once activated, the currently activated API code will immediately become invalid.
POST /v1/sofa/wallets/WALLET_ID
/apisecret/activate
An example of the request:
/v1/sofa/wallets/488471/apisecret/activate
An example of a successful response:
{
"api_code": "4PcdE9VjXfrk7WjC1",
"exp": 1609646716
}
The response includes the following parameters:
Field | Type | Description |
---|---|---|
api_code | string | The activated API code |
exp | int64 | The API code expiration unix time in UTC |
HTTP Code | Error Code | Error | Message | Description |
---|---|---|---|---|
403 | - | Forbidden. Invalid ID | - | No wallet ID found |
403 | - | Forbidden. Header not found | - | Missing X-API-CODE , X-CHECKSUM header or query param t |
403 | - | Forbidden. Invalid timestamp | - | The timestamp t is not in the valid time range |
403 | - | Forbidden. Invalid checksum | - | The request is considered a replay request |
403 | - | Forbidden. Invalid API code | - | X-API-CODE header contains invalid API code |
403 | - | Invalid API code for wallet {WALLET_ID} | - | The API code mismatched |
403 | - | Forbidden. Checksum unmatch | - | X-CHECKSUM header contains wrong checksum |
403 | - | Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) | - | Send requests too frequently |
403 | 385 | API Secret not valid | - | Invalid API code permission |
Query the API code info of a certain wallet. Use the inactivated
API code in any request will activate it. Once activated, the currently activated API code will immediately become invalid.
VIEW
GET /v1/sofa/wallets/WALLET_ID
/apisecret
An example of the request:
/v1/sofa/wallets/488471/apisecret
An example of a successful response:
{
"valid": {
"api_code": "H4Q6xFZgiTZb37GN",
"exp": 1583144863
},
"inactivated": {
"api_code": "32PmGCjNzXda4mNHX"
}
}
The response includes the following parameters:
Field | Type | Description |
---|---|---|
valid | object | The activated API code |
inactivated | object | Not active API code |
api_code | string | The API code for querying wallet |
exp | int64 | The API code expiration unix time in UTC |
Use an invalid API-CODE, the caller will get a 403 Forbidden error.
HTTP Code | Error Code | Error | Message | Description |
---|---|---|---|---|
403 | - | Forbidden. Invalid ID | - | No wallet ID found |
403 | - | Forbidden. Header not found | - | Missing X-API-CODE , X-CHECKSUM header or query param t |
403 | - | Forbidden. Invalid timestamp | - | The timestamp t is not in the valid time range |
403 | - | Forbidden. Invalid checksum | - | The request is considered a replay request |
403 | - | Forbidden. Invalid API code | - | X-API-CODE header contains invalid API code |
403 | - | Invalid API code for wallet {WALLET_ID} | - | The API code mismatched |
403 | - | Forbidden. Checksum unmatch | - | X-CHECKSUM header contains wrong checksum |
403 | - | Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) | - | Send requests too frequently |
403 | 385 | API Secret not valid | - | Invalid API code permission |
Use paired refresh code to acquire the new inactive API code/secret of the wallet.
POST /v1/sofa/wallets/WALLET_ID
/refreshsecret
An example of the request:
/v1/sofa/wallets/357818/refreshsecret
{
"refresh_code":"3EbaSPUpKzHJ9wYgYZqy6W4g43NT365bm9vtTfYhMPra"
}
The request includes the following parameters:
Field | Type | Note | Description |
---|---|---|---|
refresh_code | string | required | The corresponding refresh code of the API code specified in the X-API-CODE header |
An example of a successful response:
{
"api_code": "4QjbY3qES4tEh19PU",
"api_secret": "3jC1qjr4mrKxfoXkxoN27Uhmbm1E",
"refresh_code": "HcN17gxZ3ojrBYSXnjKsU9Pun8krP6J9Pn678k4rZ13m"
}
The response includes the following parameters:
Field | Type | Description |
---|---|---|
api_code | string | The new inactive API code |
api_secret | string | The API secret |
refresh_code | string | The paired refresh code |
HTTP Code | Error Code | Error | Message | Description |
---|---|---|---|---|
403 | - | Forbidden. Invalid ID | - | No wallet ID found |
403 | - | Forbidden. Header not found | - | Missing X-API-CODE , X-CHECKSUM header or query param t |
403 | - | Forbidden. Invalid timestamp | - | The timestamp t is not in the valid time range |
403 | - | Forbidden. Invalid checksum | - | The request is considered a replay request |
403 | - | Forbidden. Invalid API code | - | X-API-CODE header contains invalid API code |
403 | - | Invalid API code for wallet {WALLET_ID} | - | The API code mismatched |
403 | - | Forbidden. Checksum unmatch | - | X-CHECKSUM header contains wrong checksum |
403 | - | Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) | - | Send requests too frequently |
403 | 385 | API Secret not valid | - | Invalid API code permission |
400 | 112 | Invalid parameter | - | Malformatted post body or the refresh code is invalid |
Get wallet basic information.
VIEW
GET /v1/sofa/wallets/WALLET_ID
/info
An example of the request:
/v1/sofa/wallets/488471/info
An example of a successful response:
{
"currency": 60,
"currency_name": "ETH",
"address": "0xd11Bd6E308b8DC1c5243D54cf41A427Ca0F46943",
"token_name": "TTF TOKEN",
"token_symbol": "TTF",
"token_contract_address": "0xd0ee17a4e1866c1ac53a54cc2cd4dd64b503cf40",
"token_decimals": "18"
}
The response includes the following parameters:
Field | Type | Description |
---|---|---|
currency | int64 | Registered coin types. Refer to Currency Definition |
currency_name | string | Name of currency |
address | string | Wallet address |
Refer to here for more detailed currency definitions
If WALLET_ID
is a token wallet, the following fields present:
Field | Type | Description |
---|---|---|
token_name | string | Token name |
token_symbol | string | Token symbol |
token_contract_address | string | Token contract address |
token_decimals | string | Token decimals |
HTTP Code | Error Code | Error | Message | Description |
---|---|---|---|---|
403 | - | Forbidden. Invalid ID | - | No wallet ID found |
403 | - | Forbidden. Header not found | - | Missing X-API-CODE , X-CHECKSUM header or query param t |
403 | - | Forbidden. Invalid timestamp | - | The timestamp t is not in the valid time range |
403 | - | Forbidden. Invalid checksum | - | The request is considered a replay request |
403 | - | Forbidden. Invalid API code | - | X-API-CODE header contains invalid API code |
403 | - | Invalid API code for wallet {WALLET_ID} | - | The API code mismatched |
403 | - | Forbidden. Checksum unmatch | - | X-CHECKSUM header contains wrong checksum |
403 | - | Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) | - | Send requests too frequently |
403 | 385 | API Secret not valid | - | Invalid API code permission |
Check if the address conforms to the wallet cryptocurrency address format (for example, ETH must have the prefix 0x, BTC should start with 1, 3 or bc1, etc).
If the wallet's cryptocurrency is BNB or XRP, there will be a
must_need_memo
flag to indicate whether the address needs a memo / destination tag when transferring cryptocurrency to that address.
VIEW
POST /v1/sofa/wallets/WALLET_ID
/addresses/verify
Wallet ID must be a deposit or withdraw wallet's ID
An example of the request:
/v1/sofa/wallets/488471/addresses/verify
{
"addresses": [
"0x635B4764D1939DfAcD3a8014726159abC277BecC",
"1CK6KHY6MHgYvmRQ4PAafKYDrg1ejbH1cE"
]
}
The request includes the following parameters:
Field | Type | Note | Description |
---|---|---|---|
addresses | array | requried | Specify the address for verification |
An example of a successful response:
{
"result": [
{
"address": "0x635B4764D1939DfAcD3a8014726159abC277BecC",
"valid": true,
"must_need_memo": false
},
{
"address": "1CK6KHY6MHgYvmRQ4PAafKYDrg1ejbH1cE",
"valid": false,
"must_need_memo": false
}
]
}
The response includes the following parameters:
Field | Type | Description |
---|---|---|
result | array | Array of addresses' verification result |
must_need_memo | boolean | Indicate whether the address needs a memo / destination tag when transferring cryptocurrency to that address |
HTTP Code | Error Code | Error | Message | Description |
---|---|---|---|---|
403 | - | Forbidden. Invalid ID | - | No wallet ID found |
403 | - | Forbidden. Header not found | - | Missing X-API-CODE , X-CHECKSUM header or query param t |
403 | - | Forbidden. Invalid timestamp | - | The timestamp t is not in the valid time range |
403 | - | Forbidden. Invalid checksum | - | The request is considered a replay request |
403 | - | Forbidden. Invalid API code | - | X-API-CODE header contains invalid API code |
403 | - | Invalid API code for wallet {WALLET_ID} | - | The API code mismatched |
403 | - | Forbidden. Checksum unmatch | - | X-CHECKSUM header contains wrong checksum |
403 | - | Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) | - | Send requests too frequently |
403 | 385 | API Secret not valid | - | Invalid API code permission |
400 | 112 | Invalid parameter | - | Malformatted post body |
Use to inspect the notification and withdrawal authentication endpoint.
VIEW
POST /v1/sofa/wallets/WALLET_ID
/notifications/inspect
An example of the request:
/v1/sofa/wallets/896541/notifications/inspect
{
"test_number": 102999
}
The request includes the following parameters:
Field | Type | Note | Description |
---|---|---|---|
test_number | int64 | requried | The test number will be sent to the notification endpoint in the format {"msg":"CONNECTION TEST","server_time":1622195270,"client_ip":"xxx.xxx.xxx.xxx","test_number":102999} . |
An example of a successful response:
{
"server_time": 1622195253,
"client_ip": "::1",
"notification_endpoint": {
"url": "http%3A%2F%2Flocalhost%3A8889%2Fv1%2Fmock%2Fwallets%2Fcallback",
"status_code": 400,
"response": "NDAw"
},
"withdrawal_authentication_endpoint": {
"error": "no endpoint found"
}
}
The response includes the following parameters:
Field | Type | Description |
---|---|---|
server_time | int64 | Current server unix time in UTC |
client_ip | string | The request client IP |
notification_endpoint | struct | Specify the test result of notification endpoint |
withdrawal_authentication_endpoint | struct | Specify the test result of withdrawal authentication endpoint |
url | string | The escaped endpoint URL |
status_code | int | The HTTP response status code from endpoint |
response | string | The base64 encoded response from endpoint |
error | string | Specify the connection error if any |
HTTP Code | Error Code | Error | Message | Description |
---|---|---|---|---|
403 | - | Forbidden. Invalid ID | - | No wallet ID found |
403 | - | Forbidden. Header not found | - | Missing X-API-CODE , X-CHECKSUM header or query param t |
403 | - | Forbidden. Invalid timestamp | - | The timestamp t is not in the valid time range |
403 | - | Forbidden. Invalid checksum | - | The request is considered a replay request |
403 | - | Forbidden. Invalid API code | - | X-API-CODE header contains invalid API code |
403 | - | Invalid API code for wallet {WALLET_ID} | - | The API code mismatched |
403 | - | Forbidden. Checksum unmatch | - | X-CHECKSUM header contains wrong checksum |
403 | - | Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) | - | Send requests too frequently |
403 | 385 | API Secret not valid | - | Invalid API code permission |
400 | 112 | Invalid parameter | - | Malformatted post body |
List all wallets can be accessed by the inquiry read-only API code.
VIEW
GET /v1/sofa/wallets/readonly/walletlist
The API code must be a read-only API code.
An example of the request:
/v1/sofa/wallets/readonly/walletlist
An example of a successful response:
{
"total": 2,
"wallets": [
{
"address": "2NAnSkEp6SpUPLsdP3ChvN6K5qPMZyoB3RF",
"currency": 0,
"currency_name": "BTC",
"decimals": "8",
"type": 2,
"wallet_id": 101645
},
{
"address": "0x85AfD8F88C0347aFF89AFc6C0749322719396616",
"currency": 60,
"currency_name": "ETH",
"decimals": "18",
"token_contract_address": "0xdf2ce4af00b10644d00316b3d99e029d82d5d2f3",
"token_decimals": "18",
"token_name": "JGB2",
"token_symbol": "JGB2",
"type": 0,
"wallet_id": 118970
}
]
}
The response includes the following parameters:
Field | Type | Description |
---|---|---|
address | string | Wallet address |
currency | int64 | Registered coin types. Refer to Currency Definition |
currency_name | string | Name of currency |
decimals | string | Decimals of currency |
type | int | Wallet Type. Refer to Wallet Type Definition |
wallet_id | int64 | Wallet ID |
token_name | string | Token name |
token_symbol | string | Token symbol |
token_contract_address | string | Token contract address |
token_decimals | string | Token decimals |
HTTP Code | Error Code | Error | Message | Description |
---|---|---|---|---|
403 | - | Forbidden. Invalid ID | - | No wallet ID found |
403 | - | Forbidden. Header not found | - | Missing X-API-CODE , X-CHECKSUM header or query param t |
403 | - | Forbidden. Invalid timestamp | - | The timestamp t is not in the valid time range |
403 | - | Forbidden. Invalid checksum | - | The request is considered a replay request |
403 | - | Forbidden. Invalid API code | - | X-API-CODE header contains invalid API code |
403 | - | Invalid API code for wallet {WALLET_ID} | - | The API code mismatched |
403 | - | Forbidden. Checksum unmatch | - | X-CHECKSUM header contains wrong checksum |
403 | - | Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) | - | Send requests too frequently |
403 | 385 | API Secret not valid | - | Invalid API code permission |
Query balance of all wallets can be accessed by the inquiry read-only API code.
VIEW
GET /v1/sofa/wallets/readonly/walletlist/balances?type=type
&start_index=start_index
&request_number=request_number
The API code must be a read-only API code.
An example of the request:
/v1/sofa/wallets/readonly/walletlist/balances
The request includes the following parameters:
Field | Type | Note | Description |
---|---|---|---|
type | int | optional, default -1 |
Specify the wallet type want to query. Supports Vault, Deposit and Withdrawal wallet type. Refer to Wallet Type Definition |
start_index | int | optional, default 0 |
Specify start index |
request_number | int | optional, default 50 , max 100 |
Request count |
An example of a successful response:
{
"total": 104,
"wallet_balances": [
{
"balance": "1",
"type": 0,
"wallet_id": 417702
},
{
"balance": "0.35673727953125",
"token_balance": "0.00000099",
"type": 0,
"wallet_id": 426493
},
{
"balance": "4.661838507219943297",
"token_id_balances": [
{
"balance": "4",
"token_id": "2001"
},
{
"balance": "50000",
"token_id": "2004"
},
{
"balance": "0",
"token_id": "2005"
}
],
"type": 0,
"wallet_id": 661159
},
{
"balance": "0.010000000000000000",
"pool_balance": "0.414979",
"type": 2,
"wallet_id": 520474
},
{
"balance": "27.46735753510800289",
"token_balance": "0",
"type": 3,
"wallet_id": 100587
}
]
}
The response includes the following parameters:
Field | Type | Description |
---|---|---|
wallet_id | int64 | Wallet ID |
wallet_name | string | Wallet Name |
address | string | Wallet address |
currency | int64 | Registered coin types. Refer to Currency Definition |
currency_name | string | Name of currency |
decimals | string | Decimals of currency |
type | int | Wallet Type. Refer to Wallet Type Definition |
token_name | string | Token name |
token_symbol | string | Token symbol |
token_contract_address | string | Token contract address |
token_decimals | string | Token decimals |
error | boolean | Set to true if the balance query fails |
balance | string | Wallet balance. For token wallet this is mapping wallet's balance. |
unconfirm_balance | string | Unconfirmed wallet balance. For token wallet this is mapping wallet's unconfirmed balance. |
token_balance | string | Wallet token balance |
unconfirm_token_balance | string | Unconfirmed wallet token balance |
pool_balance | string | Wallet pool address balance (Deposit Wallet only) |
pool_unconfirm_token_balance | string | Wallet Pool address unconfirmed balance (Deposit Wallet only) |
token_id_balances | array | For ERC1155 token wallet |
Refer to Support Unconfirmed Balance Currency for the currencies that support the unconfirmed balance.
HTTP Code | Error Code | Error | Message | Description |
---|---|---|---|---|
403 | - | Forbidden. Invalid ID | - | No wallet ID found |
403 | - | Forbidden. Header not found | - | Missing X-API-CODE , X-CHECKSUM header or query param t |
403 | - | Forbidden. Invalid timestamp | - | The timestamp t is not in the valid time range |
403 | - | Forbidden. Invalid checksum | - | The request is considered a replay request |
403 | - | Forbidden. Invalid API code | - | X-API-CODE header contains invalid API code |
403 | - | Invalid API code for wallet {WALLET_ID} | - | The API code mismatched |
403 | - | Forbidden. Checksum unmatch | - | X-CHECKSUM header contains wrong checksum |
403 | - | Forbidden. Call too frequently ({THROTTLING_COUNT} calls/minute) | - | Send requests too frequently |
403 | 385 | API Secret not valid | - | Invalid API code permission |
- Put sample code to {YOUR_GO_PATH}/github.com/cybavo/SOFA_MOCK_SERVER
- Execute
- glide install
- go build ./mockserver.go
- ./mockserver
Configure CYBAVO API server URL in mockserver.app.conf
api_server_url="BACKEND_SERVER_URL"
- Get API code/secret on web control panel
- API_CODE, API_SECRET, WALLET_ID
- Put API code/secret to mock server's databasĂĄ
curl -X POST -H "Content-Type: application/json" -d '{"api_code":"API_CODE","api_secret":"API_SECRET"}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/apitoken
Operate on web control panel
Notification Callback URL
http://localhost:8889/v1/mock/wallets/callback
Withdrawal Authentication Callback URL
http://localhost:8889/v1/mock/wallets/withdrawal/callback
The withdrawal authentication callback URL once set, every withdrawal request will callback this URL to get authentication to proceed withdrawal request.
Refer to WithdrawalCallback() function in mock server OuterController.go
For BNB, XLM, XRP or EOS wallet:
curl -X POST -H "Content-Type: application/json" -d '{"count":2,"memos":["10001","10002"]}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/addresses
For wallet excepts BNB, XLM, XRP and EOS:
curl -X POST -H "Content-Type: application/json" -d '{"count":2}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/addresses
curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/addresses?start_index=0&request_number=1000
curl 'http://localhost:8889/v1/mock/wallets/{WALLET_ID}/addresses/contract_txid?txids={TXID1},{TXID2}'
curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/pooladdress
curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/pooladdress/balance
curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/addresses/invalid-deposit
curl 'http://localhost:8889/v1/mock/wallets/{WALLET_ID}/receiver/notifications/txid/{TX_ID}/{VOUT_INDEX}'
curl -X POST -H "Content-Type: application/json" -d '{"notification_id":0}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/collection/notifications/manual
curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/receiver/balance
curl -X POST -H "Content-Type: application/json" -d '{"address":"0x2B974a3e0b491bB26e0bF146E6cDaC36EFD574a","label":"take-some-notes"}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/addresses/label
curl -X POST -H "Content-Type: application/json" -d '{"addresses":["0x2B974a3De0b491bB26e0bF146E6cDaC36EFD574a","0xF401AC94D9672e79c68e56A6f822b666E5A7d644"]}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/addresses/get_labels
curl -X POST -H "Content-Type: application/json" -d '{"addresses":["0x46d4AD967F68253f61D45a044dC7dC7B13E5A4B3","0x107FF19Ea5fB7de78392e7AcC2A2C7eace891bDc"]}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/receiver/addresses/verify
curl -X POST -H "Content-Type: application/json" -d '{"requests":[{"order_id":"888888_1","address":"0x60589A749AAC632e9A830c8aBE042D1899d8Dd15","amount":"0.0001","memo":"memo-001","user_id":"USER01","message":"message-001"},{"order_id":"888888_2","address":"0xf16B7B8900F0d2f682e0FFe207a553F52B6C7015","amount":"0.0002","memo":"memo-002","user_id":"USER01","message":"message-002"}]}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/sender/transactions
curl -X POST http://localhost:8889/v1/mock/wallets/{WALLET_ID}/sender/transactions/{ORDER_ID}/cancel
curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/sender/transactions/{ORDER_ID}
curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/sender/transactions/{ORDER_ID}/all
curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/sender/transactions/eventlog?txid={TXID}
curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/sender/balance
curl 'http://localhost:8889/v1/mock/wallets/{WALLET_ID}/sender/notifications/order_id/{ORDER_ID}'
curl -X POST -H "Content-Type: application/json" -d '{"acl":"192.168.101.55"}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/sender/transactions/acl
curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/sender/whitelist/config
curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/sender/transactions
curl -X POST -H "Content-Type: application/json" -d '{"message":"This is proof that I, user A, have access to this address."}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/signmessage
curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/contract/read?contract=0xad6d458402f60fd3bd25163575031acdce07538d&data=0xdd62ed3e000000000000000000000000d11bd6e308b8dc1c5243d54cf41a427ca0f46943000000000000000000000000e592427a0aece92de3edee1f18e0157c05861564
curl -X POST -H "Content-Type: application/json" -d '{"items":[{"address":"GCIFMEYIEWSX3K6EOPMEJ3FHW5AAPD6NW76J7LPBRAKD4JZKTISKUPHJ","memo":"85666","user_id":"USER002"}]}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/sender/whitelist
curl -X DELETE -H "Content-Type: application/json" -d '{"items":[{"address":"GCIFMEYIEWSX3K6EOPMEJ3FHW5AAPD6NW76J7LPBRAKD4JZKTISKUPHJ","memo":"85666","user_id":"USER002"}]}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/sender/whitelist
curl -X POST -H "Content-Type: application/json" -d '{"address":"GCIFMEYIEWSX3K6EOPMEJ3FHW5AAPD6NW76J7LPBRAKD4JZKTISKUPHJ","memo":"85666","user_id":"USER002"}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/sender/whitelist/check
curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/sender/whitelist
curl -X POST -H "Content-Type: application/json" -d '{"notification_id":0}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/sender/notifications/manual
curl 'http://localhost:8889/v1/mock/wallets/{WALLET_ID}/notifications?from_time=1561651200&to_time=1562255999&type=2'
curl -X POST -H "Content-Type: application/json" -d '{"ids":[90000000140,90000000139]}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/notifications/get_by_id
curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/blocks
curl -X POST -H "Content-Type: application/json" -d '{"block_num":1}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/autofee
curl -X POST -H "Content-Type: application/json" -d '{"block_nums":[1,5,10]}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/autofees
curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/transactions?start_index=0&from_time=1559664000&to_time=1562255999&request_number=8
curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/vault/balance
curl -X POST http://localhost:8889/v1/mock/wallets/{WALLET_ID}/apisecret/activate
curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/apisecret
curl -X POST -H "Content-Type: application/json" -d '{"refresh_code":"3EbaSPUpKzHJ9wYgYZqy6W4g43NT365bm9vtTfYhMPra"}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/refreshsecret
curl http://localhost:8889/v1/mock/wallets/{WALLET_ID}/info
curl -X POST -H "Content-Type: application/json" -d '{"addresses":["0x635B4764D1939DfAcD3a8014726159abC277BecC","1CK6KHY6MHgYvmRQ4PAafKYDrg1ejbH1cE"]}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/addresses/verify
curl -X POST -H "Content-Type: application/json" -d '{"test_number":102999}' \
http://localhost:8889/v1/mock/wallets/896541/notifications/inspect
curl http://localhost:8889/v1/mock/wallets/readonly/walletlist
curl http://localhost:8889/v1/mock/wallets/readonly/walletlist/balances
Field | Type | Description | ||||||||||||||||||
type | int |
|
||||||||||||||||||
serial | int | The unique serial of callback | ||||||||||||||||||
order_id | string | The unique order ID of withdrawal request | ||||||||||||||||||
currency | string | Cryptocurrency of the callback This field is for human reading only and may change in the future. Do not use this string as currency definition, use the fields currency_bip44 and token_address as currency definition. |
||||||||||||||||||
txid | string | Transaction identifier | ||||||||||||||||||
block_height | int64 | The block height show the transaction was packed in which block | ||||||||||||||||||
tindex | int | The index of transaction in its block | ||||||||||||||||||
vout_index | int | The index of vout in its transaction | ||||||||||||||||||
amount | string | Transaction amount denominated in the smallest cryptocurrency unit | ||||||||||||||||||
fees | string | Mining fee denominated in the smallest cryptocurrency unit | ||||||||||||||||||
broadcast_at | int64 | When to broadcast the transaction in UTC time | ||||||||||||||||||
chain_at | int64 | When was the transaction packed into block (in chain) in UTC time | ||||||||||||||||||
from_address | string | The source address of the transaction | ||||||||||||||||||
to_address | string | The destination address of the transaction | ||||||||||||||||||
wallet_id | int64 | The wallet ID of the callback | ||||||||||||||||||
state | int |
Possible states (listed in the Transaction State Definition table)
|
||||||||||||||||||
confirm_blocks | int64 | Number of confirmations | ||||||||||||||||||
processing_state | int |
|
||||||||||||||||||
addon | key-value pairs |
The extra information of this callback
|
||||||||||||||||||
decimal | int | The decimal of cryptocurrency | ||||||||||||||||||
currency_bip44 | int64 | Refer to Currency Definition table | ||||||||||||||||||
token_address | string | The contract address of cryptocurrency | ||||||||||||||||||
memo | string | The memo/destination tag of the transaction |
ID | State | Description | Callback | Callback Type |
---|---|---|---|---|
0 | Init | The withdrawal request has been enqueued in the CYBAVO SOFA system | - | - |
1 | Processing | The withdrawal request is processing in the CYBAVO SOFA system | O | Withdrawal(2) |
2 | TXID in pool | The withdrawal transaction is pending in the fullnode mempool | O | Withdrawal(2) |
3 | TXID in chain | The transaction is already on the blockchain | O | Deposit(1), Withdrawal(2), Collect(3) |
4 | TXID confirmed in N blocks | The withdrawal transaction is already on the blockchain and satisfy confirmations | - | - |
5 | Failed | Fail to create the withdrawal transaction | O | Withdrawal(2) |
6 | Resent | The transaction has been successfully resent | - | - |
7 | Blocked due to risk controlled | The deposit or withdrawal transaction was temporarily blocked due to a violation of the risk control rules | - | - |
8 | Cancelled | The withdrawal request is cancelled via web console | O | Withdrawal(2) |
9 | UTXO temporarily not available | The withdrawal request has been set as pending due to no available UTXO | - | - |
10 | Dropped | A long-awaited withdrawal transaction that does not appear in the memory pool of the fullnode will be regarded as dropped | O | Withdrawal(2) |
11 | Transaction Failed | The withdrawal transaction is regarded as a failed transaction by the fullnode | O | Withdrawal(2) |
12 | Paused | The withdrawal request has been paused | - | - |
Callback sample:
If the
state
of callback is 5 (Failed), the detailed failure reason will put inaddon
field (key iserr_reason
). See the callback sample bellow.
{
"type": 1,
"serial": 90000000619,
"order_id": "",
"currency": "ETH",
"txid": "0xc99a4941f87364c9679fe834f99bc12cbacfc577dedf4f34c4fd8833a68a0b00",
"block_height": 8336269,
"tindex": 43,
"vout_index": 0,
"amount": "500000000000000000",
"fees": "945000000000000",
"memo": "",
"broadcast_at": 1595296751,
"chain_at": 1595296751,
"from_address": "0x8382Cc1B05649AfBe179e341179fa869C2A9862b",
"to_address": "0x32d638773cB85965422b3B98e9312Fc9392307BC",
"wallet_id": 5,
"state": 3,
"confirm_blocks": 2,
"processing_state": 2,
"addon": {
"fee_decimal": 18
},
"decimal": 18,
"currency_bip44": 60,
"token_address": ""
}
Callback with state 5 (Failed) sample:
{
"type": 2,
"serial": 20000000155,
"order_id": "1_69",
"currency": "ETH",
"txid": "",
"block_height": 0,
"tindex": 0,
"vout_index": 0,
"amount": "1000000000000000",
"fees": "",
"memo": "",
"broadcast_at": 0,
"chain_at": 0,
"from_address": "",
"to_address": "0x60589A749AAC632e9A830c8aBE041899d8Dd15",
"wallet_id": 2,
"state": 5,
"confirm_blocks": 0,
"processing_state": 0,
"addon": {
"err_reason": "Illegal Transaction Format: To 0x60589A749AAC632e9A830c8aBE041899d8Dd15"
},
"decimal": 18,
"currency_bip44": 60,
"token_address": ""
}
Deposit callback with blocklist_tags sample:
{
"type": 1,
"serial": 90000002797,
"order_id": "",
"currency": "ETH",
"txid": "0xbb38e22c33cbc33ad5a58a88bfee0905968062fe34e33eb6e28861771686cf45",
"block_height": 11075566,
"tindex": 7,
"vout_index": 0,
"amount": "10000000000000000",
"fees": "31500000315000",
"memo": "",
"broadcast_at": 1632195931,
"chain_at": 1632195931,
"from_address": "0xD5909BacFc1faD78e4e45E9e2feF8b4e61c8Fd0d",
"to_address": "0x319b269ef02AB7e6660f7e6cb181D0CD06E2E4a0",
"wallet_id": 854512,
"processing_state": 2,
"addon": {
"address_label": "",
"aml_screen_pass": false,
"aml_tags": {
"cybavo": {
"score": 100,
"tags": [
"TEST"
],
"blocked": true
}
},
"blocklist_tags": [
"cybavo(100): TEST"
],
"fee_decimal": 18
},
"decimal": 18,
"currency_bip44": 60,
"token_address": ""
}
ID | Description |
---|---|
1 | Deposit Callback |
2 | Withdraw Callback |
3 | Collect Callback |
4 | Airdrop Callback |
-1 | All callbacks (for inquiry) |
ID | Currency Symbol | Decimals |
---|---|---|
0 | BTC | 8 |
2 | LTC | 8 |
3 | DOGE | 8 |
5 | DASH | 8 |
60 | ETH | 18 |
144 | XRP | 6 |
145 | BCH (BCHN) | 8 |
148 | XLM | 7 |
194 | EOS | 4 |
195 | TRX | 6 |
236 | BSV | 8 |
283 | ALGO | 6 |
354 | DOT | 10 |
434 | KSM | 12 |
461 | FIL | 18 |
472 | AR | 12 |
501 | SOL | 9 |
539 | FLOW | 8 |
700 | XDAI | 18 |
714 | BNB | 8 |
966 | MATIC | 18 |
1001 | TT | 18 |
1023 | ONE | 18 |
1776 | L-BTC | 8 |
1815 | ADA | 6 |
5353 | HNS | 6 |
52752 | CELO | 18 |
99999999986* | KUB | 18 |
99999999987* | KOVAN | 18 |
99999999988* | AVAX-C | 18 |
99999999989* | PALM | 18 |
99999999990* | FTM | 18 |
99999999991* | OKT | 18 |
99999999992* | OPTIMISM | 18 |
99999999993* | ARBITRUM | 18 |
99999999994* | HECO | 18 |
99999999996* | WND | 12 |
99999999997* | BSC | 18 |
Refer to here for more detailed currency definitions
The * mark represents the definition of pseudo-cryptocurrency in the CYBAVO SOFA system
KOVAN is PoA testnet for Ethereum.
ID | Currency Symbol |
---|---|
0 | BTC |
2 | LTC |
3 | DOGE |
5 | DASH |
60 | ETH |
145 | BCH (BCHN) |
236 | BSV |
700 | XDAI |
966 | MATIC |
1023 | ONE |
1776 | L-BTC |
52752 | CELO |
99999999986 | KUB |
99999999987 | KOVAN |
99999999988 | AVAX-C |
99999999989 | PALM |
99999999990 | FTM |
99999999991 | OKT |
99999999992 | OPTIMISM |
99999999993 | ARBITRUM |
99999999994 | HECO |
99999999997 | BSC |
L-BTC only shows the unconfirmed incoming balance, no outgoing balance.
Currency | Description |
---|---|
XRP | Up to 32-bit unsigned integer (max 4294967295) |
XLM | Up to 20 chars |
EOS | Up to 256 chars |
BNB | Up to 128 chars |
Type | Description |
---|---|
0 | Vault wallet |
1 | Batch wallet |
2 | Deposit wallet |
3 | Withdrawal wallet |
5 | Deposit-withdrawal hybrid wallet |