API Documentation

Basics

Everything you need to know to get started.

# Introduction

Our free API requires no sign up and is easy to get started with. It enables the integration of: Bitcoin, Bitcoin Cash and Litecoin payments in your web applications.

# Approaches

We offer multiple approaches, catered to fit your requirements:

  • Approach A enables payments on a per-cryptocurrency basis.
  • Approach B enables payments via one, or more, cryptocurrencies based on a fiat currency and amount. It makes use of charge tokens, which are used in conjunction with the Charge UI plugin.

If you require a SDK, please explore our Library.

# Rate limit

We want our API to be operational without friction, but we do uphold a sensible rate limit. We throttle your usage to 120 requests per minute.

# Requests

You may request our secure endpoints using: cURL, a SDK, or by using your preferred programming language.

Once your project is live please enable SSL encryption to circumvent man-in-the-middle attacks.

# Testnet

The API works seamlessly with the Testnet, enabling you to create deposit addresses and send amounts to them, without occurring transaction fees.

We provide a Testnet Broadcaster, where you may send fake payments to any deposit address created on the Testnet.

tip

Please do not send real payments to any addresses created on the Testnet - our systems will not detect them.

To enable the Testnet, simply switch the URI segment:

  • /api to /api/testnet

If you're using a SDK, toggle to the Testnet using its documented method.

# Responses

Each API endpoint responds with JSON, adhering to the following format:

Response object
Key Type Description
success boolean Whether the request was successful or not.
message string The related success or error message.
results object The corresponding data results.

We also respond with meaningful HTTP status codes, look out for these:

Response status codes
Code Description
200 The request was successful.
201 The request was successful and resource was created.
400 The request was not validated or formatted properly.
404 The given input or resource was not found.
405 The request method was not supported.
429 You exceeded the given rate limit.
500 We experienced an internal server error.
503 We are down for maintenance. (99.9% uptime)

# Statuses

Statuses indicate changes in a payment's lifespan. Let's revise them now:

Payment statuses
Status Description
balance_insufficient Funds were received at the deposit address, but did not reach the expected amount.
balance_sufficient

Funds were received at the deposit address and reached the expected amount.

Check for this status if you do not care for confirmations.
balance_sufficient_confirmed

Funds are sufficient and have at least one confirmation.

One confirmation takes between 2-15 minutes, depending on the network type and load.

Check for this status if you require stronger payment security.
output_completed

Funds were forwarded to your output address.

Happens shortly after the payment confirms.

# Currencies

At present, we accept 3 cryptocurrencies. Each have their own minimum deposit amount, service fee and forwarding miner fee:

Accepted cryptocurrencies
Currency Minimum Deposit Service Fee Miner Fee
btc 0.0002 ($5.75)

1%
(0.0001 minimum)

30 sat per byte
bch 0.0002 ($0.03)

1%
(0.0001 minimum)

1 sat per byte
ltc 0.003 ($0.24)

1%
(0.001 minimum)

19 sat per byte

# Conversion

At some stage, you might want to convert some fiat amount into cryptocurrency. To do so, you may request the convert endpoint:

GET /api/convert/{fiat}/{amount}/{currency}
Wildcard Type Value Description
fiat string gbp|usd|eur The fiat currency to convert from.
amount float ie. 2.59 The amount of fiat currency to convert.
currency string btc|bch|ltc The cryptocurrency to convert the amount to.
Response results object
200
Key Type Description
fiat string The fiat currency converted from.
amount float The amount of fiat currency.
currency string The cryptocurrency converted to.
rate float The conversion rate.
float float The converted amount as a float.
satoshis integer The converted amount in satoshis.
timezone string The server timezone.
timeflux string The current server time.

Approach A

This approach enables payments on a per-cryptocurrency basis.

# Payment Creation

To create a new payment address, request the following endpoint:

POST /api/create/{currency}
Wildcard Type Value Description
currency string btc|bch|ltc The cryptocurrency payment address to create.

Make sure to include your desired POST parameters:

Request parameters
Param Type Required Description
amount integer ✓

The amount to charge in satoshis.

Make sure it meets the minimum.
output_address string ✓ The output address we forward the payment to.

Make sure the address is valid.
secret string

Any secret identifier corresponding to the payment. You can use it to verify our incoming webhooks.
callback_url string

The webhook URL we POST payment statuses and details to.
expires integer

The minutes until the deposit address expires.

Defaults to 60. Has minimum of 30 and maximum of 120.
Response results object
201
Key Type Description
address object The address object.
address.testnet boolean Whether the address belongs to the testnet or not.
address.label string The address label which identifies the payment.
address.currency string The deposit address currency.
address.chain string The deposit address chain identifier.
address.deposit_address string The deposit address.
address.expected_amount integer The expected deposit amount in satoshis.
address.output_address string The supplied output address we forward the payment to.
address.callback_url string The supplied webhook URL where we notify payment statuses.
address.expires_unix integer The UNIX expiry timestamp.
address.expires_at string The expiry timestamp.
address.created_at string The created timestamp.
timezone string The server timezone.

# Payment Monitoring

The best way to check whether a payment was successful is via webhook notifications. We POST Statuses individually to your supplied callback_url.

Here's an overview of the POST data we send:

Webhook POST data
Param Type Description
label string The address label which identifies the payment.
secret string The secret identifier you supplied us with when creating the payment, if any.
status string The current payment status.
details object Object containing details related to the status.

Please respond with a 200 status code when you receive a webhook.

tip

If we are unable to establish a connection with your host, or you do not respond successfully, we will retry every 10 minutes, for a total of 3 times per status change.

Alternatively, you may use an address.label to manually check for its payment Statuses:

GET /api/statuses/{label}
Wildcard Type Description
label string The address label which identifies the payment.
Response results object
200
Key Type Description
statuses array The list of status objects, ordered by most recent.
statuses[x].status string The payment status.
statuses[x].details object The status details.
statuses[x].created_at string The status timestamp.
address object The address object.
timezone string The server timezone.

Approach B

This approach enables payments via one, or more, cryptocurrencies based on a fiat currency and amount. It makes use of charge tokens, which are used in conjunction with the Charge UI plugin.

# Charge Tokens

To generate a new charge token, request the following endpoint:

POST /api/charge/{fiat}
Wildcard Type Value Description
fiat string eur|gbp|usd The fiat currency to charge in.

Make sure to include the following POST parameters:

Request parameters
Param Type Required Description
amount float ✓

The fiat amount to charge.

We require a minimum charge of 3.00.
accept array ✓

The array of cryptocurrencies you want to accept and their corresponding output addresses.

Here's an example:

accept[btc] = 1FRHEjRR3wYNFVNPtPh3YLa212dH1XZ2R1
Response results object
201
Key Type Description
charge object The charge object.
charge.testnet boolean Whether the charge belongs to the testnet or not.
charge.token string The public charge token.
charge.fiat string The fiat currency to charge in.
charge.amount float The fiat amount to charge.
charge.accept object The accepted cryptocurrencies and their output addresses.
charge.locked_at string The timestamp the charge payment was made and locked.
charge.created_at string The created timestamp.
timezone string The server timezone.

Use the charge.token with the Charge UI plugin. This will render an interface where the user can select which cryptocurrency to pay.

# Charge Monitoring

To check whether a payment was successful, you can use a charge.token to monitor its Statuses at the following endpoint:

GET /api/charge/{token}
Wildcard Type Description
label token The charge token which identifies the payment.
Response results object
200
Key Type Description
statuses array The list of status objects, ordered by most recent.
statuses[i].currency string The payment status cryptocurrency.
statuses[i].status string The payment status.
statuses[i].details object The payment status details.
statuses[i].created_at string The payment status timestamp.
charge object The charge object.
timezone string The server timezone.