Withdraw Assets
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.
Request
POST /v1/sofa/wallets/{WALLET_ID}/sender/transactions
WALLET_ID
must be a withdrawal wallet ID
Post Body
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 |
amount | string | required | Withdrawal amount |
memo | string | optional | Memo on blockchain (This memo will be sent to blockchain). Refer to [Memo Requirement]({{ ref “memo-requirement” >}}) |
user_id | string | optional | Specify certain user |
message | string | optional | Message (This message only savced on CYBAVO, not sent to blockchain) |
block_average_fee | int | optional, range 1~30 |
Use average blockchain fee within latest N blocks |
manual_fee | int | optional, range 1~1000 |
Specify blockchain fee in smallest unit of wallet currency |
ignore_black_list | boolean | optional, default false |
After setting, the address check will not be performed. |
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.
Response Body
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. |
Error Code
HTTP Code | Error Code | Error | Message | Description |
---|---|---|---|---|
403 | - | Forbidden. Invalid wallet 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 |
400 | 112 | Invalid parameter | - | Malformatted post body |
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 | HTTP resp failed {HTTP_CODE}, body: {RESPONSE_BODY} | The authentication callback URL returned status code other than 200 |
403 | 827 | Outgoing address in black list, abort transaction | - | Some outgoing addresses are blacklisted, examine the response ‘blacklist’ field for detailed information |
404 | 304 | Wallet ID invalid | - | The wallet is not allowed to perform this request |
404 | 312 | Policy not found | - | No active withdrawal policy found |
404 | 703 | Operation failed | Unrecognized response: {RESPONSE_BODY}, ‘OK’ expected | The withdrawal request is not allowed by authentication callback URL |
Sample Request
API
/v1/sofa/wallets/94533/sender/transactions
Post Body
order_id
is 888888_ in following sample request
{
"requests": [
{
"order_id": "888888_1",
"address": "0x60589A749AAC632e9A830c8aBE042D1899d8Dd15",
"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",
"memo": "memo-002",
"user_id": "USER02",
"message": "message-002",
"manual_fee": 50
},
{
"order_id": "888888_3",
"address": "0x9638fa816ccd35389a9a98a997ee08b5321f3eb9",
"amount": "0.0002",
"memo": "memo-003",
"user_id": "USER03",
"message": "message-003"
}
],
"ignore_black_list": false
}
Response Body
{
"results": {
"1": 20000000001,
"2": 20000000002
}
}
Sample cURL Command
curl -X POST -H "Content-Type: application/json" -d '{"requests":[{"order_id":"888888_1","address":"0x60589A749AAC632e9A830c8aBE042D1899d8Dd15","amount":"0.01","memo":"memo-001","user_id":"USER01","message":"message-001"},{"order_id":"888888_2","address":"0xf16B7B8900F0d2f682e0FFe207a553F52B6C7015","amount":"2.5","memo":"memo-002","user_id":"USER02","message":"message-002"}]}' \
http://localhost:8889/v1/mock/wallets/{WALLET_ID}/withdraw