curl --request POST \
--url https://www.coinpayments.net/api.php \
--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'
The following are a collection of potential use cases for the CoinPayments API with example steps for integration.
Prerequisites for tutorials
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.
This tutorial will cover integrating the following features using the CoinPayments.net API:
Prerequisites for this tutorial include:
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 CoinPayments.net 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).
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 CoinPayments.net 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 CoinPayments.net 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 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 |
| buyer_email | sample@gmail.com |
| ipn_url | https://www.sampleplatform.com/ipn-handler-script |
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:
This tutorial will cover integrating the following features using the CoinPayments.net API.
Some example scenarios that this tutorial would apply to include:
The required data from the withdrawing system's perspective is as follows:
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 |
| ipn_url | https://www.sampleplatform.com/ipn-handler-script |
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:
This tutorial covers converting coins in your CoinPayments.net 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 CoinPayments.net 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 CoinPayments.net 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:
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.
