# V1
## General information
Api endpoint for all requests is:
```
https://app.wllxpay.io/api/v1
```
#### Deposit flow
1. You obtain new address from WllxPay API (for some currencies it may be address and tag) and store it somewhere on your side. After that you show this address to your customer in order to make a deposit.
2. Customer sends some funds to this address.
3. When transaction is sent by a customer - WllxPay sends a callback to your callback url with transaction details. It contains status, address, currency, amount and fees. \
If status is successful, you should deposit respective amount to customer balance on your side.
#### Withdrawal flow
1. You request to send amount of money to address.
2. Your request is validated on our side. If signature is correct, address is valid and you have enough balance - WllxPay responds you with the transaction object.
3. You will receive a callback when transaction status is updated.
## API Endpoints
## Take new address for deposit
`POST` `https://app.wllxpay.io/api /v1/addresses/take`
This method is used for obtaining deposit for receiving funds
#### Request Body
| Name | Type | Description |
| ----------- | ------ | ------------------------------------------------------------------------------------------- |
| foreign\_id | string | Any id from your side. We recommend using this parameter to identify customer on your side. |
| currency | string | Currency ISO you want to receive, for example: **BTC** |
{% tabs %}
{% tab title="201 If all is ok you will receive address object" %}
```
{
"status": "ok",
"data": {
"id": 1,
"address": "1xds1983rh13ouifhj12fjo214f2f",
"foreign_id": "1872",
"tag": "tag-1"
}
}
```
{% endtab %}
{% tab title="400 In case of any errors you will receive json with human-readable error description" %}
```
{
"errors": {
"currency": "Currency BTC is not enabled for your merchant"
},
"error_code": "forbidden_currency"
}
```
{% endtab %}
{% endtabs %}
{% hint style="warning" %}
Please not that some cryptocurrencies require few parameters to receive funds, not only an address but also a "**tag**". For example Ripple (XRP) requires tag in order to send funds.\
If response has a non-empty tag parameter, please **make sure to pass this "tag"** to your customer otherwise this may lead to funds being delayed or lost.
{% endhint %}
## Withdraw
`POST` `https://app.wllxpay.io/api/v1/withdrawal/make`
Request funds withdraw
#### Request Body
| Name | Type | Description |
| ----------- | ------ | --------------------------------------------------- |
| currency | string | Currency iso: BTC |
| foreign\_id | string | Foreign id - unique identifier for your transaction |
| amount | string | Amount to send |
| address | string | Address to withdraw currency, for example : |
{% tabs %}
{% tab title="201 " %}
```
{
"status": "ok",
"data": {
"id": 1,
"currency": "BTC",
"currency_fee": "BTC",
"address": "address-string",
"tag": null,
"amount": "1.01",
"status": "processing"
}
}
```
{% endtab %}
{% tab title="400 " %}
```
{
"errors": {
"amount": "The amount field is required.",
"foreign_id": "The foreign id field is required.",
"address": "The address field is required.",
"currency": "The currency field is required."
},
"error_code": "not_enough_balance"
}
```
{% endtab %}
{% tab title="422 " %}
```
{
"errors": {
"amount": "Not enough amount",
"foreign_id": "The Foreign ID has already been taken.",
"currency": "Invalid balance."
},
"error_code": "not_enough_balance"
}
```
{% endtab %}
{% endtabs %}
{% hint style="danger" %}
Foreign\_id is used to identify the withdrawal. Foreign\_id is a unique string that you send to WllxPay to avoid network issues and double sending of funds, and used to identify your requests. \
Common approach is to insert transaction record to your MySQL or any other relational database before calling withdrawal API, and send to WllxPay id from autoincrement field in your database.
{% endhint %}
## Callbacks
For any transaction, deposit or withdrawal, transaction callback will come to the url that you specified in your merchant dashboard.
{% tabs %}
{% tab title="Deposit BTC" %}
```
{
"id": "1127742",
"txid": "5145d00f9fe21cae7c0f94938ed91f8b493fae610f839703fde89aa2c5642bde",
"currency": "BTC",
"currency_fee": "BTC",
"confirmations": "0",
"amount": "0.01496462",
"fee": "0.00000000",
"address": "32dJKfbQLoHQVimtjt1U2h7Vw2kcbJbGVp",
"type": "deposit",
"status": "confirmed",
"error": ""
}
```
{% endtab %}
{% tab title="Withdraw BTC" %}
```
{
"id": "1127738",
"txid": "7266a32b9c893d62612f706b0c9f66fd20616dc86c46f68eefecbb7c3f9003be",
"foreign_id": "457630",
"currency": "BTC",
"currency_fee": "BTC",
"confirmations": "0",
"amount": "0.05190000",
"fee": "0.00057960",
"address": "1GCzAsthZADkcFH4VJyYvtcNuWQmXoavpx",
"type": "withdrawal",
"status": "confirmed",
"error": ""
}
```
{% endtab %}
{% tab title="Deposti XRP" %}
```
{
"id": "216097",
"txid": "F78BE636A02CEE67EB36D87FAB90A098FA4946CBCB23726303A8AE6DA98BBD5C",
"currency": "XRP",
"currency_fee": "XRP",
"confirmations": "12",
"amount": "1399.75000000",
"fee": "0.00000000",
"address": "r3S9W2pYZj7vBueA8scxdJBSEVU2wjMedB",
"tag": "246861"
"type": "deposit",
"status": "confirmed",
"error": "",
}
```
{% endtab %}
{% endtabs %}
To provide authentication for the callback, coinspaid API signs the POST your api key and secret:
1. **X-Processing-Key** – Your public key
2. **X-Processing-Signature** – POST body, signed by the your secret key HMAC-SHA512
{% hint style="info" %}
**Read this if you accept tokens.**\
Please pay attention to having 2 currency fields - "currency" and "currency\_fee". \
For USDT or ERC20 tokens "**currency**" will be USDT or \*TOKENNAME\* and **"currency\_fee"** will be BTC or ETC / ETH, because in USDT blockchain fees are paid in BTC and in ERC20 fees paid by ETC / ETH respectively.
{% endhint %}
#### Transaction types can be:
| Type | Meaning |
| ---------- | --------------------------------------- |
| deposit | Money arrived to your wallet from payer |
| withdrawal | Money sent from your wallet to address |
## Transaction statuses:
| Status | Meaning |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------- |
| confirmed | **Final**. You are safe to process this transaction |
| not\_confirmed | Transaction is not yet confirmed |
| error | **Final**. Some error occurred, pls see “error” field |
| cancelled | **Final**. This transaction is a double spend. Pay attention to this customer. |
| not\_enough\_fee | Not enough money to pay fee for transfers of ETH / ERC20 / USDT, when money are deposited transactions will try to transfer |
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://wllxpay.gitbook.io/wllxpay-documentation/api-documentation/v1.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.