Wallet API

  • Description
  • API endpoint
  • Request limits
  • Service fee
  • Wallet
    • post Create wallet
    • post Create wallet payment address
    • post Preauthorize payment
    • post Send payment
    • post Send all available balance
    • post Send payment with commitment
    • get Wallet state
    • get Wallet transaction list
    • get Wallet pending transaction list
    • get Wallet confirmed transaction list
    • get Wallet commitment state
    • get Wallet commitments list
    • get Wallet pending commitments list
    • get Wallet completed commitments list
    • get Wallet address list
    • get Wallet address transaction list
    • get Daily wallet statistics
  • Callback
    • post Callback handler
    • get Callback log for payment address
    • get Callback log for payment

Wallet API

version 1

Wallet API is a service that provides the ability to receive and send payments using API requests. Funds on the wallet are fully controlled by the service, we recommend storing only operational stock for payments. For large amounts and long-term storage of cryptocurrencies, use cold storages that are fully controlled by you.

The wallets service can be used to accept payments on website, similar to payment forwarding services. The difference is that the transfer of funds does not occur and when a payment is received at the generated address, the wallet balance is replenished.

Each wallet can have an unlimited number of replenishment addresses, which allows using one wallet for the entire set of addresses issued to users . Addresses have an unlimited period of validity. Each address can have an individual link for notification of received payments or use the common link specified for the wallet in case the individual callback link is not specified.

When creating the wallet, it is recommended to set a password and use it requests with HMAC signature.

API endpoint

For all supported cryptocurrencies, APIs are available for Mainnet, Testnet, and the Tor network. Created addresses in the same network can be used for all supported cryptocurrencies in this network (ex. ETH and USDT-ERC20, USDC-ERC20). For testnet networks available coins faucet and explorers. For Ethereum testnet please use Sepolia Network.

Mainnet URL: https://api.bitaps.com/{currency}/v1/
Testnet URL: https://api.bitaps.com/{currency}/testnet/v1/
Tor Mainnet URL: http://bitaps4nifcusilt.onion/{currency}/v1/

Available currency value: btc, ltc, eth, usdt-erc20, usdc-erc20.

Request limits

For API, restrictions of requests by IP addresses apply. Standard limit 60 requests within 5 seconds for a single IP address. If you need more requests, then you need to purchase an API token. For questions about obtaining a token API, contact support@bitaps.com. If the limit is exceeded, a page with the status 429 to many requests is given in response to the request. If an error is received, you should wait for the time limit to be restored, otherwise the IP address will be blocked for 3 minutes. The current status of the limits can be found in the response headers Ratelimit-Remaining and Ratelimit-Reset .

Service fee

The service charges a flat rate commission from each payment received or sent. The miners commission paid when sending the payment is included in the service fee.

Commissions:

CurrencyService fee Additional receiver Min. TX Value
Bitcoin incoming0.00005 BTC > 0.00000546 BTC + Service fee
Bitcoin with commitment outgoing0.00005 BTC > 0.00000546 BTC + Service fee
Bitcoin instant outgoing (mempool fee rate < 75 s/vByte)0.00045 BTC 0.00001 BTC
Bitcoin instant outgoing (mempool fee rate < 160 s/vByte)0.00045 BTC 0.00001 BTC
Bitcoin instant outgoing ( mempool fee rate > 160 s/vByte)0.00060 BTC 0.00001 BTC
Ethereum0.0015 ETH> 0.001 ETH + Service fee
Litecoin0.0004 LTC 0.00003 LTC > 0.00000546 LTC + Service fee
USDT-ERC207 USDT> 1 USDT + Service fee
USDC-ERC207 USDC> 1 USDC + Service fee

Wallet

Create wallet
post /create/wallet

When creating a wallet, it is recommended to specify a password with which all requests for transactions with the wallet will be signed by the HMAC. Optionally, a link for incoming / outgoing payment notifications can be specified.

Request returns the ID of the created wallet. An example of the ID of the created wallet: BTCv5QsMiXRDeNjx7RSWyQAdLS4wxniJ6L57rBaSWqBW4tW3fTPmt . If during the creation of the wallet a password was set, API calls for such a wallet should be signed with HMAC signature. If the wallet password was not set, we draw your attention to the fact that you should keep the wallet ID secret, the use of a wallet that is not password protected is not recommended.

Create HMAC signature:

key = double_sha256(wallet_id + password)

msg = wallet_id + nonce

HMAC_signature = HMAC(key, msg)

Nonce and HMAC_signature should be in request headers.

Access-Nonce: nonce

Access-Signature: HMAC_signature

Request body
application/json
JSON object
    callback_link
string
Link to the payment notification handler
optional
    password
string
Password
optional
Responses
application/json
200
wallet_id
string
Wallet ID
required
currency
string
Currency
required
Create wallet payment address
post /create/wallet/payment/address

Create a payment address for the wallet. Optionally, an individual callback link can be specified for the address. In case the link is not specified, the callback specified for the wallet will be used. If the wallet callback was also not specified, no notifications will be sent.

Request body
application/json
JSON object
    wallet_id
string
Wallet ID
optional
    callback_link
string
Link to the payment notification handler
optional
    confirmations
string
Number of confirmations for payment notification, default 3
optional
Responses
application/json
200
invoice
string
Public ID for payment address
required
payment_code
string
Payment code, used to authenticate payment notifications (this code should not be disclosed for security reasons)
required
address
string
Payment address
required
legacy_address
string
Payment address in old format
optional
confirmations
string
Number of confirmations for payment notification
required
callback_link
string
Link to the payment notification handler
required
wallet_id
string
Wallet ID
required
currency
string
Currency
required
Preauthorize payment
post /wallet/send/payment/preauthorize/{wallet_id}
Preauthorize payment with available wallet balance, get service fee.
Headers parameters
Access-Nonce
number
Nonce used for HMAC signature
optional
Access-Signature
string
HMAC signature
optional
Path parameters
wallet_id
string
Wallet ID
required
Request body
application/json
JSON object
    receivers_list
array
Receivers list [{"address":{address}, "amount":{amount}, ...], maximum 100 recipients
optional
    message
object
{"format": ["text"|"base64"], "payload": {string}} message length should not exceed 80 characters for text format and 80 bytes for base64 format
optional
Responses
application/json
200
fee
number
Recent service fee
required
authorization
string
Success
required
Send payment
post /wallet/send/payment/{wallet_id}
Sending an instant payment using the available wallet balance. When requesting an outgoing payment, the list of recipients is indicated, the service fee is charged to the first recipient for the additional recipient, charged fee for the additional recipient.
Headers parameters
Access-Nonce
number
Nonce used for HMAC signature
optional
Access-Signature
string
HMAC signature
optional
Path parameters
wallet_id
string
Wallet ID
required
Request body
application/json
JSON object
    receivers_list
array
Receivers list [{"address":{address}, "amount":{amount}, ...], maximum 100 recipients
optional
    message
object
{"format": ["text"|"base64"], "payload": {string}} message length should not exceed 80 characters for text format and 80 bytes for base64 format
optional
Responses
application/json
200
tx_list
array
required
   address
string
required
   tx_hash
string
required
   out
integer
optional
   amount
integer
required
message
object
optional
   tx_hash
string
required
   out
integer
optional
Send all available balance
post /wallet/send/all/balance/{wallet_id}
Sending an instant payment using all available wallet balance.
Headers parameters
Access-Nonce
number
Nonce used for HMAC signature
optional
Access-Signature
string
HMAC signature
optional
Path parameters
wallet_id
string
Wallet ID
required
Request body
application/json
JSON object
    address
string
receiver address
optional
Responses
application/json
200
tx_list
array
required
   address
string
required
   tx_hash
string
required
   out
integer
required
   amount
integer
required
Send payment with commitment
post /wallet/send/payment/with/commitment/{wallet_id}
Sending payment with commitment using available wallet balance. Commitment payment means that you receive commitment code as response for request. The commitment will be fulfilled within 10 - 30 minutes in most cases. The transaction hash and output index will become available by API request using commitment code. The advantage of this sending method is the low commission achieved by aggregating payments.
Headers parameters
Access-Nonce
number
Nonce used for HMAC signature
optional
Access-Signature
string
HMAC signature
optional
Path parameters
wallet_id
string
Wallet ID
required
Request body
application/json
JSON object
    receiver
object
{"address":{address}, "amount":{amount}}
required
Responses
application/json
200
commitment
string
Commitment code
required
type
string
transaction type [commitment or internal]
required
status
string
Commitment status
required
amount
number
required
address
string
required
Wallet state
get /wallet/state/{wallet_id}
Information about the state of the wallet: balance, number of transactions, number of wallet addresses.
Headers parameters
Access-Nonce
number
Nonce used for HMAC signature
optional
Access-Signature
string
HMAC signature
optional
Path parameters
wallet_id
string
Wallet ID
required
Responses
application/json
200
wallet_id
string
Wallet ID
required
balance_amount
integer
Wallet balance
required
address_count
integer
Wallet address count
required
create_date_timestamp
integer
Date of creation of the wallet in UNIX timestamp format
required
sent_tx
integer
Outgoing transactions count
required
pending_sent_tx
integer
Unconfirmed outgoing transactions count
required
service_fee_paid_amount
integer
Amount of paid service fee
required
pending_received_amount
integer
Amount of unconfirmed transactions
required
received_tx
integer
Count of incoming transactions
required
create_date
string
Creation time in format ISO UTC 0
required
invalid_tx
integer
Count of invalid transactions
required
sent_amount
integer
Amount of outgoing transactions
required
pending_received_tx
integer
Count of unconfirmed transactions
required
last_used_nonce
integer
Last used Nonсе
required
received_amount
integer
Amount of incoming transactions
required
pending_sent_amount
integer
Amount of outgoing unconfirmed transactions
required
Wallet transaction list
get /wallet/transactions/{wallet_id}
Headers parameters
Access-Nonce
number
Nonce used for HMAC signature
optional
Access-Signature
string
HMAC signature
optional
GET parameters
from
number
Beginning of range in unix timestamp
optional
to
number
Ending of range in unix timestamp
optional
limit
number
Records on page
optional
page
number
Page number
optional
Responses
application/javascript
200
pending_transactions
object
required
   next_page
boolean
required
   tx_list
array
required
transactions
object
required
   next_page
boolean
required
   tx_list
array
required
      timeline_sent_count
integer
Count of sent transactions before the current transaction
optional
      timestamp
integer
Date of confirmation of the transaction in the format UNIX timestamp
optional
      block_height
integer
Block number in the blockchain in which this transaction is included
optional
      create_timestamp
integer
Creation date of the transaction in the UNIX timestamp format
optional
      timeline_received_count
integer
Count of transactions received before the current transaction
optional
      amount
integer
Transaction amount
optional
      hash
string
Transaction hash
optional
      timeline_balance
integer
Wallet balance to current transaction
optional
      out
integer
Out number
optional
      fee
integer
service fee
optional
      type
string
optional
      timeline_invalid_count
integer
Number of invalid transaction before current transaction
optional
      address
string
Receiver address
optional
      time
string
Transaction confirmation time in format ISO UTC 0
optional
Wallet pending transaction list
get /wallet/pending/transactions/{wallet_id}
Headers parameters
Access-Nonce
number
Nonce used for HMAC signature
optional
Access-Signature
string
HMAC signature
optional
GET parameters
from
number
Beginning of range in unix timestamp
optional
to
number
Ending of range in unix timestamp
optional
limit
number
Records on page
optional
page
number
Page number
optional
Responses
application/javascript
200
next_page
boolean
required
tx_list
array
required
   timeline_sent_count
integer
Count of sent transactions before the current transaction
optional
   timestamp
integer
Date of confirmation of the transaction in the format UNIX timestamp
optional
   block_height
integer
Block number in the blockchain in which this transaction is included
optional
   create_timestamp
integer
Creation date of the transaction in the UNIX timestamp format
optional
   timeline_received_count
integer
Count of transactions received before the current transaction
optional
   amount
integer
Transaction amount
optional
   hash
string
Transaction hash
optional
   timeline_balance
integer
Wallet balance to current transaction
optional
   out
integer
Out number
optional
   fee
integer
service fee
optional
   type
string
optional
   timeline_invalid_count
integer
Number of invalid transaction before current transaction
optional
   address
string
Receiver address
optional
   time
string
Transaction confirmation time in format ISO UTC 0
optional
Wallet confirmed transaction list
get /wallet/confirmed/transactions/{wallet_id}
Headers parameters
Access-Nonce
number
Nonce used for HMAC signature
optional
Access-Signature
string
HMAC signature
optional
GET parameters
from
number
Beginning of range in unix timestamp
optional
to
number
Ending of range in unix timestamp
optional
limit
number
Records on page
optional
page
number
Page number
optional
Responses
application/javascript
200
next_page
boolean
required
tx_list
array
required
   timeline_sent_count
integer
Count of sent transactions before the current transaction
optional
   timestamp
integer
Date of confirmation of the transaction in the format UNIX timestamp
optional
   block_height
integer
Block number in the blockchain in which this transaction is included
optional
   create_timestamp
integer
Creation date of the transaction in the UNIX timestamp format
optional
   timeline_received_count
integer
Count of transactions received before the current transaction
optional
   amount
integer
Transaction amount
optional
   hash
string
Transaction hash
optional
   timeline_balance
integer
Wallet balance to current transaction
optional
   out
integer
Out number
optional
   fee
integer
service fee
optional
   type
string
optional
   timeline_invalid_count
integer
Number of invalid transaction before current transaction
optional
   address
string
Receiver address
optional
   time
string
Transaction confirmation time in format ISO UTC 0
optional
Wallet commitment state
get /wallet/commitment/{commitment_code}
Responses
application/javascript
200
wallet_id_hash
string
required
amount
number
required
address
string
required
fee
number
required
tx_hash
string
required
out
number
required
completed_timestamp
string
required
create_timestamp
string
required
currency
string
required
Wallet commitments list
get /wallet/commitments/{wallet_id}
Headers parameters
Access-Nonce
number
Nonce used for HMAC signature
optional
Access-Signature
string
HMAC signature
optional
GET parameters
from
number
Beginning of range in unix timestamp
optional
to
number
Ending of range in unix timestamp
optional
limit
number
Records on page
optional
page
number
Page number
optional
Responses
application/javascript
200
next_page
boolean
required
commitments_list
array
required
Wallet pending commitments list
get /wallet/pending/commitments/{wallet_id}
Headers parameters
Access-Nonce
number
Nonce used for HMAC signature
optional
Access-Signature
string
HMAC signature
optional
GET parameters
from
number
Beginning of range in unix timestamp
optional
to
number
Ending of range in unix timestamp
optional
limit
number
Records on page
optional
page
number
Page number
optional
Responses
application/javascript
200
next_page
boolean
required
commitments_list
array
required
Wallet completed commitments list
get /wallet/completed/commitments/{wallet_id}
Headers parameters
Access-Nonce
number
Nonce used for HMAC signature
optional
Access-Signature
string
HMAC signature
optional
GET parameters
from
number
Beginning of range in unix timestamp
optional
to
number
Ending of range in unix timestamp
optional
limit
number
Records on page
optional
page
number
Page number
optional
Responses
application/javascript
200
next_page
boolean
required
commitments_list
array
required
Wallet address list
get /wallet/addresses/{wallet_id}
Headers parameters
Access-Nonce
number
Nonce used for HMAC signature
optional
Access-Signature
string
HMAC signature
optional
GET parameters
from
number
Beginning of range in unix timestamp
optional
to
number
Ending of range in unix timestamp
optional
limit
number
Records on page
optional
page
number
Page number
optional
Responses
application/javascript
200
next_page
boolean
required
address_list
array
required
   received_amount
integer
Amount received by the address
optional
   received_tx
integer
Count of incoming transactions received by the address
optional
   pending_received_amount
integer
Pending amount received by the address
optional
   pending_received_tx
integer
Count of incoming unconfirmed transactions received by the address
optional
   timestamp
integer
Date of creation of the address in the format UNIX timestamp
optional
   time
string
Date of creation of the address in the format ISO UTC 0
optional
   address
string
Address
optional
Wallet address transaction list
get /wallet/address/transactions/{wallet_id}/{address}
Headers parameters
Access-Nonce
number
Nonce used for HMAC signature
optional
Access-Signature
string
HMAC signature
optional
GET parameters
from
number
Beginning of range in unix timestamp
optional
to
number
Ending of range in unix timestamp
optional
limit
number
Records on page
optional
page
number
Page number
optional
Responses
application/javascript
200
pending_transactions
object
optional
   tx_list
array
optional
   next_page
boolean
optional
transactions
object
optional
   tx_list
array
optional
      timeline_received_count
integer
optional
      type
string
optional
      time
string
optional
      block_height
integer
optional
      timeline_balance
integer
optional
      out
integer
optional
      address
string
optional
      timestamp
integer
optional
      amount
integer
optional
      timeline_invalid_count
integer
optional
      hash
string
optional
      create_timestamp
integer
optional
      timeline_sent_count
integer
optional
      fee
integer
optional
      create_time
string
optional
   next_page
boolean
optional
Daily wallet statistics
get /wallet/daily/statistic/{wallet_id}
Headers parameters
Access-Nonce
number
Nonce used for HMAC signature
optional
Access-Signature
string
HMAC signature
optional
GET parameters
from
number
Beginning of range in unix timestamp
optional
to
number
Ending of range in unix timestamp
optional
limit
number
Records on page
optional
page
number
Page number
optional
Responses
application/javascript
200
day_list
array
required
   balance_amount
integer
Balance at the end of the day
optional
   date
string
Date
optional
   datestamp
integer
Date in format UNIX timestamp / 86400
optional
   address_count
integer
Count of wallet addresses
optional
   received_amount
integer
Amount received per day
optional
   received_tx
integer
Count of recharge transactions per day
optional
   pending_received_amount
integer
Unconfirmed amount received per day at the end of the day
optional
   pending_received_tx
integer
Count of unconfirmed recharge transactions per day at the end of the day
optional
   pending_received_amount_total
integer
Unconfirmed amount including previous days at the end of the day
optional
   pending_received_tx_total
integer
Count of unconfirmed recharge transactions including previous days at the end of the day
optional
   sent_amount
integer
Amount sent per day
optional
   sent_tx
integer
Count of daily debit transactions
optional
   pending_sent_amount
integer
Unconfirmed amount sent per day at the end of the day
optional
   pending_sent_tx
integer
Count of uncommitted transactions sent per day at the end of the day
optional
   pending_sent_amount_total
integer
Unconfirmed sent amount including previous days at the end of the day
optional
   pending_sent_tx_total
integer
Count of unconfirmed balance sent transactions including previous days at the end of the day
optional
   service_fee_paid_amount
integer
Service fee paid
optional
   invalid_tx
integer
optional
next_page
boolean
next page flag
optional

Callback

Callback handler
post /callback/handler/example

Description of the payment notification handler with the description of the incoming POST parameters. Payment notifications are received when the following events occur.:

  • new payment detected
  • count of confirmations changed
  • count of payment confirmations has reached the specified value and the payment is confirmed

For example, if a payment address is created with 2 confirmations, it will receive the following notifications: unconfirmed, pending [1/2], confirmed.

The logic for processing payment notifications should be as follows. Each payment address corresponds to a confirmed and unconfirmed balance. N - the number of required confirmations.

Processing incoming notifications:

  • confirmations = 0 check if there is a payment in the database (unique payment identifier = transaction hash + out number), if not exist, then we insert it to the database and add an unconfirmed balance to the user
  • 0 < confirmations < N check if there is a payment in the database, if not, then insert it in the database and add an unconfirmed balance to the user
  • confirmations >= N check if there is a payment in the database, if there is one and it is not processed, reduce the unconfirmed balance, increase the confirmed one and mark the payment as processed. If there is no payment, then add it as processed, add the confirmed balance to the user.
Acknowledgment

Payment notifications have logic to protect against failure. As a confirmation that the notification has been received, the service expects to receive a response in the form of a code invoice code in response body for each http request.

In case no correct answer, notifications will be repeated with each new block within 24 hours. IP addresses from which notifications are sent are available via dns request to the domain name callback.bitaps.com. If the answer is not successful, repeated attempts are made from different IP addresses. To stop sending notifications, notification handler should reply with correct response to any notification with the number of payment confirmations greater than or equal to the specified value when generating a payment address.

Tor

Tor notifications supported

Responses
text/plain
200
event
string
Notification event [unconfirmed, pending [N/M], confirmed, payout sent, payout confirmed]
optional
address
string
Payment address received payment
optional
amount
string
Payment amount
optional
currency
string
Currency
optional
confirmations
string
Payment transaction confirmations
optional
tx_hash
string
Payment transaction hash
optional
tx_out
string
Payment transaction output
optional
invoice
string
Invoice code
optional
code
string
Payment code
optional
payout_tx_hash
string
Payout transaction hash
optional
payout_tx_outs
string
List of outputs with payout (btc, ltc)
optional
payout_miner_fee
string
deprecated
optional
payout_service_fee
string
service fee
optional
received_tx
string
Total transactions received by address
optional
received_amount
string
Total amount received by address
optional
pending_received_tx
string
Unconfrimed transaction count
optional
pending_received_amount
string
Total unconfirmed amount
optional
Callback log for payment address
get /payment/address/callback/log/{address}

Callback log for payment address. Authorization required by request headers Payment-Code or Access-Token.

Headers parameters
Payment-Code
string
payment code
optional
GET parameters
limit
number
limit per page
optional
page
number
Page number
optional
Responses
application/json
200
callback_list
array
Log records list
optional
   status
['string', 'array']
Payment status at the time of sending the payment notification
optional
   response
object
Response logs
optional
      request_status
integer
HTTP status
optional
      request_ip_log
array
optional
         ip
string
IP from which the notification was sent
optional
         status
integer
Status
optional
         time
integer
Request time in milliseconds
optional
      request_response
string
Response string
optional
      request_success
boolean
Notification status
optional
      request_id
integer
Notification id
optional
      request_error
string
Notification error
optional
   time
string
The time of sending the notification in ISO UTC 0 format
optional
   timestamp
integer
The time of sending the notification in unix timestamp format
optional
   event
string
Notification event
optional
   confirmations
integer
Transaction confirmation count
optional
   outpount
string
Unique payment id (transaction hash : out number)
optional
   response_status
string
Notification handler response status
optional
   amount
integer
Payment amount
optional
next_page
boolean
Next page indicator
optional
Callback log for payment
get /payment/callback/log/{tx_hash}/{output}

Callback logs for payment transaction hash. Authorization required by request headers Payment-Code or Access-Token.

Headers parameters
Payment-Code
string
payment code
optional
GET parameters
limit
number
Limit per page
optional
page
number
Page number
optional
Responses
application/json
200
callback_list
array
Log records list
optional
   status
['string', 'array']
Payment status at the time of sending the payment notification
optional
   response
object
Response logs
optional
      request_status
integer
HTTP status
optional
      request_ip_log
array
optional
         ip
string
IP from which the notification was sent
optional
         status
integer
Status
optional
         time
integer
Request time in milliseconds
optional
      request_response
string
Response string
optional
      request_success
boolean
Notification status
optional
      request_id
integer
Notification id
optional
      request_error
string
Notification error
optional
   time
string
The time of sending the notification in ISO UTC 0 format
optional
   timestamp
integer
The time of sending the notification in unix timestamp format
optional
   event
string
Notification event
optional
   confirmations
integer
Transaction confirmation count
optional
   outpount
string
Unique payment id (transaction hash : out number)
optional
   response_status
string
Notification handler response status
optional
   amount
integer
Payment amount
optional
next_page
boolean
Next page indicator
optional