CoinPayments API Sample Code

cURL Command Line Example

curl --request POST \
--url \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'HMAC: your_generated_hmac' \
--data 'version=1&cmd=rates&key=your_api_public_key&format=json'

Use Case Tutorials

The following are a collection of potential use cases for the CoinPayments API with example steps for integration.

Prerequisites for tutorials

  • A account.
  • A platform capable of making HTTP POST calls to the API.
  • Developer understanding of the introduction documentation section for the API.
  • A private and public API key (from this logged in account page).
  • Knowledge of the different coin codes, listed in the CODE column on the supported coins page. These codes (also known as tickers) are used in the API calls anytime a "currency", "to" or "from" field is needed.

Note: These tutorials do not cover the use of the "nonce" field and assume every API response format to be the default format of json.

Tutorial 1: E-Commerce System Checkout

This tutorial will cover integrating the following features using the API:

  • Convert prices from a fiat currency (USD, CAD, EUR, etc.) prices to a cryptocurrency.
  • Checkout a user by creating a transaction for their order.
  • Be notified of a completed payment by the IPN system.

Prerequisites for this tutorial include:

  • Products or services purchased in an e-commerce platform having a set price.
  • An IPN secret and server capable of receiving payment notifications from

Part A: Cryptocurrency Prices

In this example we'll assume the default currency in the e-commerce platform is USD (United States Dollar) and that the developer wishes to show their users a BTC (Bitcoin) and LTC (Litecoin) price in addition to USD.

The developer should begin by defining a data storage location for the rates they wish to show their users. All rates returned by the API will use BTC as a base rate. An example schema for this data storage would include the following columns/fields (in a traditional relational database table).

  • column | sample value
  • id | 1
  • currency | LTC
  • rate_btc | 0.018343387500000000000000
  • last_update | 1518463609

Once a form of data storage is setup the developer can setup a recurring call to our API to keep their exchange rate data up to date. Our rates are updated every 15 minutes. It should be noted that rates are only an average value and individual exchanges may buy or sell currencies at different rates.

The recurring call for rates to the API would have the following fields posted.

Field Name Value
version 1
key public_api_key
cmd rates
short 1

The "short" field set to 1 will exclude extra data in the response that isn't needed for this example. If you required the number of confirms needed or the full name for each coin, then you could set "short" to 0.

A successful call to the API will return an array of data with the rates in the "result" array. Your application's code should loop through this response array and update the data in the storage location created above, for each currency you wish to track. In this example that would only be USD, BTC and LTC.

Now that you have the rates stored in your application it's a simple matter of outputting them for display next to USD. The "rate_btc" data would be used as a common value for calculating USD to LTC, since you now know the USD→BTC rate and the LTC→BTC rates.

Part B: Checkout

The next example explains how to create a transaction using the API in order to accept payment in your e-commerce system during the checkout process. You will need to know the following information in order to create the transaction:

  • The total price in BTC that you wish to charge for the transaction.
  • An email address for the buyer.

The API command we'll use to create this transaction is "create_transaction", with only it's minimum required fields plus an IPN URL, shown with example values in the table below.

Field Name Value
version 1
key public_api_key
cmd create_transaction
amount 0.5
currency1 BTC
currency2 BTC

Note: If your products are priced in USD but you are receiving BTC, you could use currency1=USD and currency2=BTC and let the "create_transaction" command handle the conversion.

The response of this API call will return an array of data with information the user will need to complete their checkout.

A sample user flow for the checkout might look like this:

  1. User confirms their cart contents and currency for payment, clicking a "Proceed to checkout" button that triggers the "create_transaction" API call.
  2. System parses the response of the API call and renders a "Payment details" page for the user. This page would show:
    1. The amount of currency the user needs to send.
    2. The address the user needs to send the currency to, with a destination tag if applicable.
    3. The number of confirms needed on the chosen currencies blockchain.
    4. A timeout value which defines how long in seconds the user has to send and have confirmed payment, before the transaction expires.
  3. The user sends their payment and clicks on a "Payment sent" button.
  4. The user is redirected to a "Payment status" page, the URL for this page being taken from the "status_url" field value of the "create_transaction" API call's response. They can monitor the status manually from here if they wish or close the page and wait for notification from the next step.
  5. Upon completed payment, an instant payment notification (IPN) is triggered and sent to your system's IPN handler script. This script generates a notification email for the user and releases the product or service for delivery.

Tutorial 2: User Currency Withdrawal

This tutorial will cover integrating the following features using the API.

  • Having a user withdraw an amount of currency from your account to a specified currency address (outside the system).
  • The withdrawing system checking it's currency balance before initiating the withdrawal.

Some example scenarios that this tutorial would apply to include:

  • A gambling platform where the user wishes to cash out some of their account's holdings.
  • A freelancer network where a job has been completed and the service provider needs to be paid by the network's system (acting as escrow).
  • A company paying it's employees payroll from their wallet.

The required data from the withdrawing system's perspective is as follows:

  • The currency to withdraw
  • The amount of currency to withdraw
  • The address to withdraw the currency to
  • The system's IPN handler URL

A sample of the fields with their respective values that would be passed as the API call:

Field Name Value
version 1
key public_api_key
cmd create_withdrawal
amount 1
currency1 BTC
address sampleBtcAddressXyz123
auto_confirm 1

The "auto_confirm" field above would allow the withdrawal to complete without the need for an email confirmation. This is ideal for an automated system where manual human approval would be too time consuming or unnecessary.

A sample user flow for withdrawal might look like this:

  1. The withdrawing system confirms with the end user the amount, currency and address for the withdrawal.
  2. A call to the "balances" API command is made by the withdrawing system, to confirm the balance in the wallet for the chosen currency is greater than or equal to the amount of currency being withdrawn.
  3. The "create_withdrawal" API command is called by the withdrawing system. The user is notified their withdrawal request has been created.
  4. Upon completion of the withdrawal an instant payment notification (IPN) is triggered and sent to the withdrawing system's IPN handler script. This script generates a notification email for the user.

Tutorial 3: Convert Coins

This tutorial covers converting coins in your wallet from one currency to another using the API command "convert". It also explains how to first check the conversion limits for a coin pairing and confirm that a conversion for the given pair is supported. Even though a call to the "convert" command will throw an error if the coin pairing is not supported, it's good practice to check the amount you're planning to convert is within the minimum and maximum limits, with the additional benefit of finding out before making the "convert" command call if the pairing is supported or not.

The example scenario for this tutorial is that you as wallet user have 2 Bitcoin you would like to convert into other currencies to diversify your cryptocurrency holdings without going through the hassle of buying and selling on a 3rd party exchange. We will pretend you want to convert 1 Bitcoin into Litecoin and the other 1 Bitcoin into Steem. Unknown to you the Bitcoin to Steem conversion is not supported, but this will be discovered through the check of conversion limits. It will also be assumed that you want to send the converted coins to an address you manually define as opposed to being automatically sent back into your wallet.

The first step will be to check the limits and support for the Bitcoin to Litecoin conversion. The fields for the API call would be passed as follows:

Field Name Value
version 1
key public_api_key
cmd convert_limits
from BTC
to LTC

The result of this API call would be an array containing "min" and "max" values. You can then confirm the amount you intend to convert is between these values. If a "max" value of 0 is returned, that simply means there is no maximum amount for conversion. It should be noted that due to conversion provider fluctuation, limits do vary often.

Next you would call the same "convert_limits" command but replace "LTC" in the "to" field with "STEEM". This would return an error explaining that coin conversion from BTC to STEEM is not supported. Therefore we would not proceed with a "convert" command for this coin pairing.

The next step will be to initiate our coin conversion for 1 Bitcoin to Litecoin. We'll assume the results from the "convert_limits" call above had a minimum less than 1 and a maximum greater than 1, therefore meaning our amount of 1 Bitcoin is within the conversion limits. The fields for the API call would be passed as follows:

Field Name Value
version 1
key public_api_key
cmd convert
amount 1
from BTC
to LTC
address sampleLtcAddressXyz123

Note that the address field should be an valid address for the "to" currency.

The result of the "convert" command call above, if successful would return an ID for the conversion. We'll pretend this ID was "12345". You could then use the following API command and field values to lookup the status of the conversion.

Field Name Value
version 1
key public_api_key
cmd get_conversion_info
id 12345

The result of the "get_conversion_info" command call above, if successful would return a status (along with time created, amounts and currencies data) for the conversion. The values that may be returned are:

  • 2 = Complete
  • 1 = Funds Sent
  • 0 = Pending
  • -1 = Cancelled
  • -2 = Cancelled: Below ShapeShift Minimum
  • -3 = Cancelled: Above ShapeShift Maximum
  • -4 = Cancelled: No ETH available to use as gas.
  • These are all of the values at the time of this writing but it can be assumed any other negative number is a cancelled conversion as well.

That's it! You will now have converted 1 Bitcoin into it's equivalent value in Litecoin and had that Litecoin sent to the address you defined.