API documentation

The API is designed as a REST-ful. JSON data format is used for communication. We recommend calling individual methods with application/json header with UTF-8 encoding (Content-Type: application/json; charset = utf-8).

There are two types of methods:

  • public (do not require authorization) 
  • private (require authorization)

To access the private API methods, please get in touch with our customer support to obtain an authorization token {api_key}.

Authorization is executed by sending HTTP header Authorization: Bearer {api_key}

The API is available at the following URL:
/api/{endpoint}

Below, you will find description of available services (endpoints).

 

GET /status

Public method used to check status of service.

Request:
/api/status

Response:
{
     "status": "ok",
     "timestamp": 1649143742,
     "datetime": "2022-04-05T07:29:02+00:00"
}

Response parameters:
Name: status
Type: text
Description: ok - service active

Name: timestamp
Type: integer
Description: Current server time

Name: datetime
Type: datetime
Description: Current server time in ISO 8601 format

 

GET /validateAddress/{btc_address}

Public method used to validate the bitcoin address.

Request:
/api/validateAddress/n3PdePLBgEeTYk4nAhcbehsnjvr1i3LyYS

Response:
{
     "result": "true"
}

Response parameters:
Name: result
Type: boolean
Description: 
true - BTC address is valid
false - BTC address is invalid

 

POST /createTransaction

Private method used to create a new transaction.

Request:
/api/createTransaction

Request parameters:
{
     "delay":"1", 
     "payouts":[
          “mr9if7VDsVfEZ1qUo2u3trv6rU9eH7Yx4u",
          "mia3h2FdYvR2LbDR1to9u6TC62hiTbDKM9"
     ],
     "refCode":"qljncygz"
}

Name: delay
Type: integer
Description: Transaction delay in hours (the transaction won't start until the delay interval is reached)

Name: payouts
Type: array
Description: List of BTC addresses and payouts in the following format [BTC_address => BTC_amount]

Name: refCode
Type: string
Description: Affiliate program code (optional)

Response:
{
     "id": "JEVG1TKFP4L95EDX",
     "status": "pending",
     "depositAddress": "tb1qmc2vcq6a427v6t83z8rnyg9ldf5k5p5uj2x4xv",
     "depositAmount": 0.00316,
     "payouts": {
          "mr9if7VDsVfEZ1qUo2u3trv6rU9eH7Yx4u": "0",
          "mia3h2FdYvR2LbDR1to9u6TC62hiTbDKM9": "0"
          },
     "fee": 0.00016,
     "delay": "1",
     "refCode": "qljncygz",
     "updated": "2022-05-05T08:56:05+00:00",
     "created": "2022-05-05T08:56:05+00:00",
     "signature": "zDQlfJHSJWtzw8yFwevs7KmiDZs15FVl01RbPwPt3bc="
}

Response parameters:
Name: id
Type: string
Description: Transaction ID

Name: status
Type: string
Description: Transaction status
- pending - waiting for deposit 
- confirming - deposit received, waiting for one confirmation
- processing - sending payment(s) to specified address(es)
- complete - transaction completed
- expired - transaction expired

Name: depositAddress
Type: string
Description: Deposit BTC address

Name: depositAmount
Type: decimal
Description: Deposit amount = amount of payouts + fees

Name: payouts
Type: array
Description: List of BTC addresses and payout amounts

Name: fee
Type: decimal
Description: Total amount of fees

Name: delay
Type: integer
Description: Transaction delay in hours

Name: refCode
Type: string
Description: Affiliate program code

Name: updated
Type: datetime
Description: Transaction update time in ISO 8601 format

Name: created
Type: datetime
Description: Transaction creation time in ISO 8601 format

Name: signature
Type: string
Description: Signature (explained below)

 

GET /transactions

Private method used to list of all transactions, sorted from newest to oldest.

Request:
/api/transactions?limit=2&offset=0

Request parameters:
Name: limit
Type: integer
Description: Number of records returned, default = 30

Name: offset
Type: integer
Description: Paging offset, default = 0

Response:
{
     "transactions": [
          {
               "id": "Y9ANXDCJMHG2J6GD",
               "status": "pending",
               "depositAddress": "tb1qfhlu3acnqztwu2ep8mn446f8mfhkyt6u4xq2dd",
               "depositAmount": 0.00316,
               "payouts": {
                    "mr9if7VDsVfEZ1qUo2u3trv6rU9eH7Yx4u": "0.001",
                    "mia3h2FdYvR2LbDR1to9u6TC62hiTbDKM9": "0.002"
               },
               "fee": 0.00016,
               "delay": "1",
               "updated": "2022-05-05T08:52:52+00:00",
               "created": "2022-05-05T08:52:52+00:00"
          },
          {
               "id": "EEFU0IKT3BAJ1JOQ",
               "status": "expired",
               "depositAddress": "tb1qu80wgqucwvwxt3wdk8lyd4weuxn3vvy23et3p3",
               "payouts": {
                    "mx1HgMB1EG38bRtfH4tQwMGSvZXodbxdQ8": "0.005"
               },
               "fee": 0.0001,
               "delay": "0",
               "updated": "2022-04-29T11:46:05+00:00",
               "created": "2022-04-26T11:46:02+00:00"
          }
     ],
     "totalTransactions": 27,
     "limit": "2",
     "offset": 0
}

Response parameters:
Name: transactions
Type: array
Description: List of individual transactions (objects). See transaction details for more information.

Name: totalTransactions
Type: integer
Description: Number of all transactions

Name: limit
Type: integer
Description: Maximum number of records returned, default = 30

Name: offset
Type: integer
Description: Paging offset, default = 0

 

GET /transaction/{id}

Private method used to receive transaction details.

Request:
/api/transaction/Q96G3MSNW8MPQRTX

Response:
{
     "id": "Q96G3MSNW8MPQRTX",
     "status": "complete",
     "depositAddress": "tb1q0pkwdj3pqdp587yrc8sus876kccn5tq577ce5x",
     "depositAmount": "0.0062244",
     “depositTxid": "80bb6cda5036ce277598d949d2e4b3771c56b31ba77b757bf9753a370f16c99",
     "payouts": {
          "mfuAKvSsAMrC7gjbEEb521uc1myeF9BSsc": "0.006"
     },
     "txid": "0ea6f3a702a368ed09830d959f1c82b7d8f65f53a783965514380e123fc8ca4e",
     "fee": 0.0002244,
     "delay": "0",
     "updated": "2022-04-28T09:46:11+00:00",
     "created": "2022-04-28T09:42:41+00:00"
}

Response parameters:
Name: id
Type: string
Description: Transaction ID

Name: status
Type: string
Description: Transaction status:
- pending - waiting for payment (deposit)
- confirming - payment received, waiting for one confirmation
- processing - sending payments to specified addresses
- complete - transaction completed 
- expired - transaction expired

Name: depositAddress
Type: string
Description: Deposit BTC address

Name: depositAmount
Type: decimal
Description: BTC deposit amount received

Name: depositTxid
Type: string
Description: TXID of the received deposit

Name: payouts
Type: array
Description: List of BTC addresses and payouts

Name: txid
Type: string
Description: Withdrawal transaction TXID

Name: fee
Type: decimal
Description: Total amount of fees

Name: delay
Type: integer
Description: Delay of the transaction in hours

Name: refCode
Type: string
Description: Affiliate program reference code

Name: updated
Type: datetime
Description: Transaction status update time in ISO 8601 format

Name: created
Type: datetime
Description: Transaction creation time in ISO 8601 format

Name: signature
Type: string
Description: Signature (explained below)

 

Signature

Each transaction contains a "signature" parameter that confirms the data is valid and have not been altered in any way.

In addition to the authorization token {api_key}, you will also receive a private key {secret_key} from customer support. You can use the secret key to verify the "authenticity" of the received data.

Signature calculation:
$secret_key = {secret_key};
$transaction_details = 
{
     "id": "Q96G3MSNW8MPQRTX",
     "status": "complete",
     "depositAddress": "tb1q0pkwdj3pqdp587yrc8sus876kccn5tq577ce5x",
     "depositAmount": "0.0062244",
     “depositTxid": "80bb6cda5036ce277598d949d2e4b3771c56b31ba77b757bf9753a370f16c99",
     "payouts": {
          "mfuAKvSsAMrC7gjbEEb521uc1myeF9BSsc": "0.006"
     },
     "txid": "0ea6f3a702a368ed09830d959f1c82b7d8f65f53a783965514380e123fc8ca4e",
     "fee": 0.0002244,
     "delay": "0",
     "updated": "2022-04-28T09:46:11+00:00",
     "created": "2022-04-28T09:42:41+00:00"
};

$signature = base64_encode(hash_hmac('sha256', implode('|', array_map(function($a) { return is_array($a) ? implode(',', array_keys($a)).','.implode(',', $a) : $a; }, array_values($transaction_details))), $secret_key, TRUE));

Note: the order of the parameters must be identical to the answer. The "signature" parameter does not enter into the calculation.

 

Error codes

If no error occurs, each request receives an HTTP 200 OK response.

ERROR response:
{
     "code": 400,
     "description": "Invalid JSON data."
}

Response parameters:
Name: code
Type: integer
Description: Error code that matches the HTTP codes
- 400 - bad request (validation error)
- 401 - missing / invalid API key
- 403 - blocked account / API
- 404 - service (endpoint) does not exist
- 503 - service is temporarily unavailable

Name: description
Type: string
Description: Error description

Mix Bitcoins (3% fee)
By using whir, you agree to Privacy policy.