Authentication
To sign requests, you can use following code:
import time
import base64
import hashlib
import hmac
import json
import requests
API_URL = 'https://api.cryptochill.com'
API_KEY = 'my_api_key'
API_SECRET = 'my_api_secret'
def encode_hmac(key, msg, digestmod=hashlib.sha256):
return hmac.new(key.encode(), msg=msg, digestmod=digestmod).hexdigest()
def cryptochill_api_request(endpoint, payload=None, method='GET'):
payload_nonce = str(int(time.time() * 1000))
request_path = '/v1/%s/' % endpoint
payload = payload or {}
payload.update({'request': request_path, 'nonce': payload_nonce})
# Encode payload to base64 format and create signature using your API_SECRET
encoded_payload = json.dumps(payload).encode()
b64 = base64.b64encode(encoded_payload)
signature = encode_hmac(API_SECRET, b64)
# Add your API key, encoded payload and signature to following headers
request_headers = {
'X-CC-KEY': API_KEY,
'X-CC-PAYLOAD': b64,
'X-CC-SIGNATURE': signature,
}
# Make request
response = requests.request(method, API_URL + request_path, headers=request_headers)
return response.json()
profiles = cryptochill_api_request('profiles')
print(json.dumps(profiles, indent=2))
const axios = require('axios');
const Base64 = require('js-base64').Base64;
const crypto = require('crypto');
const API_URL = 'https://api.cryptochill.com';
const API_KEY = 'my_api_key';
const API_SECRET = 'my_api_secret';
function encode_hmac(key, msg) {
return crypto.createHmac('sha256', key).update(msg).digest('hex');
}
function cryptochill_api_request(endpoint, payload = {}, method = 'GET') {
const request_path = '/v1/' + endpoint + '/'
payload.request = request_path;
payload.nonce = (new Date).getTime();
// Encode payload to base64 format and create signature using your API_SECRET
const encoded_payload = JSON.stringify(payload);
const b64 = Base64.encode(encoded_payload);
const signature = encode_hmac(API_SECRET, b64);
// Add your API key, encoded payload and signature to following headers
let request_headers = {
'X-CC-KEY': API_KEY,
'X-CC-PAYLOAD': b64,
'X-CC-SIGNATURE': signature,
};
return axios({
method: method,
url: API_URL + request_path,
headers: request_headers,
});
}
cryptochill_api_request('profiles').then(function (response) {
console.log(response);
}).catch(function (error) {
console.log(error);
});
You can obtain API Keys by logging in and creating a key in Settings > API Keys. This will give you both an "API Key" that will serve as your user name, and an "API Secret" that you will use to sign messages.
All requests must contain a nonce, a number that will never be repeated and must increase between requests. This is to prevent an attacker who has captured a previous request from simply replaying that request. We recommend using a timestamp at millisecond or higher precision. The nonce need only be increasing with respect to the session that the message is on.
PAYLOAD
The payload of the requests must be a JSON object, which will be described in the documentation below. Rather than being sent as the body of the POST request, it will be base-64 encoded and stored as a header in the request.
The following three headers is all that is required to make requests to CryptoChill API:
Header | Value |
---|---|
X-CC-KEY | Your CryptoChill API Key |
X-CC-PAYLOAD | Base64-encoded JSON payload |
X-CC-SIGNATURE | hex(HMAC_SHA256(base64(payload), key=api_secret)) |
Invoices
Invoices are time-sensitive payment requests addressed to specific buyers or payers. Invoice has a unique receiving address and fixed price, typically denominated in fiat currency. It also has a BTC equivalent price, calculated by CryptoChill, with an expiration time of about 15 minutes.
List Invoices
invoices = cryptochill_api_request('invoices')
cryptochill_api_request('invoices').then(function (response) {
console.log(response);
}).catch(function (error) {
console.log(error);
});
The above command returns JSON structured like this:
{
"pagination": {
"num_pages": 1,
"count": 12,
"page": 1,
"next_page": null,
"previous_page": null,
"per_page": 25
},
"result": [
{
"id": "123",
"kind": "BTC",
"created_at": "2019-01-23T14:31:20.750500+00:00",
"profile_id": "bb519172-5823-4170-a1ba-b94143eaaaea",
"address": "3Q2sdSVxqQCyYUt4NvX2y4XNmn7PRF77PZ",
"lightning": null,
"network": "mainnet",
"status": "paid",
"amount": {
"requested": {
"amount": "99.00000000",
"currency": "USD"
},
"invoiced": {
"amount": "0.02731120",
"currency": "BTC",
"rate_usd": "3624.886995160658"
},
"paid": {
"amount": "0.02731120",
"currency": "BTC"
}
},
"custom_fee": null,
"min_confirmations": null,
"notes": null,
"passthrough": "{\"user_id\":1}"
}
]
}
This endpoint retrieves all invoices. Endpoint uses pagination and returns 25
invoices per page. Invoices are sorted by creation time in descending order.
HTTP Request
GET https://api.cryptochill.com/v1/invoices/
Query Parameters
Parameter | Default | Description |
---|---|---|
p | None | Page number. |
txid | None | Filter invoices by txid |
address | None | Filter invoices by receiving address |
status | None | Filter by status. Available values: "new", "pending", "complete", "expired". |
Get Invoice
invoice = cryptochill_api_request('invoices/42dbee1d-8659-44c3-aab2-6e414c5825a5')
cryptochill_api_request('invoices/42dbee1d-8659-44c3-aab2-6e414c5825a5').then(function (response) {
console.log(response);
}).catch(function (error) {
console.log(error);
});
The above command returns JSON structured like this:
{
"result": {
"id": "42dbee1d-8659-44c3-aab2-6e414c5825a5",
"kind": "BTC",
"created_at": "2019-02-08T01:06:11.799601+00:00",
"profile_id": "bb519172-5823-4170-a1ba-b94143eaaaea",
"address": "3Q2sdSVxqQCyYUt4NvX2y4XNmn7PRF77PZ",
"lightning": null,
"network": "mainnet",
"status": "new",
"amount": {
"requested": {
"amount": "10.00",
"currency": "USD"
},
"invoiced": {
"amount": "0.00292111",
"currency": "BTC"
},
"paid": null
},
"custom_fee": null,
"min_confirmations": null,
"notes": null,
"passthrough": "{\"user_id\": 123}",
"transactions": []
}
}
This endpoint retrieves a specific invoice.
HTTP Request
GET https://api.cryptochill.com/v1/invoices/<ID>/
URL Parameters
Parameter | Description |
---|---|
ID | The ID of the invoice to retrieve. |
Create Invoice
import json
payload = {
"amount": "10",
"currency": "USD",
"kind": "BTC",
"profile_id": "456",
"passthrough": json.dumps({"user_id": 123})
}
invoice = cryptochill_api_request('invoices', payload, 'POST')
print(json.dumps(invoices, indent=2))
var payload = {
"amount": "10",
"currency": "USD",
"kind": "BTC",
"profile_id": "456",
"passthrough": JSON.stringify({"user_id": 123})
}
cryptochill_api_request('invoices', payload, 'POST').then(function (response) {
console.log(response);
}).catch(function (error) {
console.log(error);
});
JSON response for Create Invoice endpoint:
{
"result": {
"id": "42dbee1d-8659-44c3-aab2-6e414c5825a5",
"kind": "BTC",
"created_at": "2019-02-08T01:06:11.799601+00:00",
"profile_id": "bb519172-5823-4170-a1ba-b94143eaaaea",
"address": "3Q2sdSVxqQCyYUt4NvX2y4XNmn7PRF77PZ",
"lightning": null,
"network": "mainnet",
"status": "new",
"amount": {
"requested": {
"amount": "10.00",
"currency": "USD"
},
"invoiced": {
"amount": "0.00292111",
"currency": "BTC"
},
"paid": {
"amount": "0.00292111",
"currency": "BTC"
}
},
"custom_fee": null,
"min_confirmations": null,
"notes": null,
"passthrough": "{\"user_id\": 123}",
"transactions": [
{
"id": "9094fefe-3ac2-49b3-99ec-9b719331316c",
"kind": "BTC",
"txid": "7f96054005c8aab5101d48211cb23070b6a9d9b7ea25b3422de2c109eb57fad9",
"confirmations": 6,
"amount": "0.00292111",
"created_at": "2019-02-08T01:08:11.799601+00:00"
}
]
}
}
This endpoint creates an invoice. Response is identical to Get Invoice endpoint response.
HTTP Request
POST https://api.cryptochill.com/v1/invoices/
Payload Parameters
Parameter | Description | Required |
---|---|---|
profile_id | Profile ID to use for settings, callback and wallet address generation. | Yes |
amount | Quoted decimal payment amount. Do not specify amount to use address as never-expiring deposit address. Only Transactions Callbacks will be sent if no amount is specified while creating invoice. To increase users privacy level we strongly advise creating new invoice/address for each new deposit. | No |
currency | Currency for the specified payment amount. Available values: USD, BTC, LTC, EUR, GBP, AUD, CHF. | Yes |
kind | Invoice kind / currency. Available values:BTC – Bitcoin On-chain (Default).BTC_BECH32 – Bitcoin On-Chain (Bech32 / Native Segwit address).BTC_LIGHTNING – Bitcoin Lightning Network invoice.LTC – Litecoin. |
No |
passthrough | String. Meta-data you wish to store with the invoice. Will be sent alongside all callbacks associated with the invoice. | No |
fee_amount | Custom fee amount in same currency as specified in kind field that will be deducted from paid amount response. |
No |
min_confirmations | Minimum confirmations required to change status to "confirmed" and trigger callback. Available values: 1-5. Default: Profile min_confirmations setting value. |
No |
notes | Can be product or service name or any other notes. Visible in dashboard and in public invoice link. | No |
Lightning Network
JSON response for Create Invoice with kind=lightning endpoint:
{
"result": {
...
"kind": "lightning",
"lightning": {
"payment_request": "...",
"payment_hash": "..."
},
...
}
}
If you specify lightning
for invoice kind
field then address won't be generated, instead lightning
key will be present in response having two sub-keys: payment_request
and
payment_hash
:
Parameter | Description |
---|---|
payment_request | Payment request string required for client to pay lightning network payment request. |
payment_hash | Unique ID of payment request. |
Expiration
Payment requests are valid for exact amount specified in payload data and will expire after time set in Profile Details -> Invoice Expiration or as set per specific invoice.
Invoice Callbacks
Callbacks provide same exact response format as in Get Invoice
API endpoint in result
field plus three extra fields specified in Callbacks Documentation.
Only Transactions Callbacks will be sent if no amount is specified while creating invoice.
You can view history of callbacks (if any) in CryptoChill in Invoice detail view.
Invoice Callback Statuses
Status | Description |
---|---|
invoice_pending | Sum of all incoming transactions matches requested amount (0 confirmations). |
invoice_confirmed | Sum of all incoming transactions matches requested amount (at last 1 confirmations). |
invoice_complete | Sum of all incoming transactions matches requested amount (6+ confirmations). |
invoice_incomplete | Transaction(s) were made, but amount is less than requested in the invoice. Requires manual handling. |
Transactions
Transactions are incoming Bitcoin transactions paid for invoices or any transactions deposited to any of wallets addresses.
List Transactions
transactions = cryptochill_api_request('transactions')
cryptochill_api_request('transactions').then(function (response) {
console.log(response);
}).catch(function (error) {
console.log(error);
});
The above command returns JSON structured like this:
{
"pagination": {
"num_pages": 1,
"count": 12,
"page": 1,
"next_page": null,
"previous_page": null,
"per_page": 25
},
"result": [
{
"id": "9094fefe-3ac2-49b3-99ec-9b719331316c",
"kind": "BTC",
"txid": "7f96054005c8aab5101d48211cb23070b6a9d9b7ea25b3422de2c109eb57fad9",
"invoice": {
"id": "47ad5fa7-0754-4ba8-bc2d-1cdd0dbcddaa",
"kind": "BTC",
"created_at": "2019-02-07T22:13:15.093624+00:00",
"profile_id": "bb519172-5823-4170-a1ba-b94143eaaaea",
"address": "3Q2sdSVxqQCyYUt4NvX2y4XNmn7PRF77PZ",
"lightning": null,
"network": "mainnet",
"amount": {
"requested": {
"amount": "10.00",
"currency": "USD"
},
"invoiced": {
"amount": "0.00293528",
"currency": "BTC"
}
},
"custom_fee": null,
"min_confirmations": null,
"notes": null,
"passthrough": "{\"test\":123}"
},
"amount": {
"paid": {
"amount": "0.00293528",
"currency": "BTC",
"quotes": {
"USD": "10.00"
}
}
},
"created_at": "2019-02-07T22:13:28.681005+00:00",
"executed_at": "2019-02-07T22:21:59+00:00",
"confirmed_at": "2019-02-07T23:09:31.983230+00:00",
"confirmations": 6,
"status": "complete",
"network": "mainnet"
}
]
}
This endpoint retrieves all transactions. Endpoint uses pagination and returns 25
transactions per page. Transactions are sorted by creation time in descending order.
HTTP Request
GET https://api.cryptochill.com/v1/transactions/
Query Parameters
Parameter | Default | Description |
---|---|---|
p | None | Page number. |
txid | None | Filter transactions by txid |
address | None | Filter transactions by receiving address |
invoice_id | None | Filter transactions by Invoice ID |
Get Transaction
transaction = cryptochill_api_request('transactions/asd123')
cryptochill_api_request('transactions/asd123').then(function (response) {
console.log(response);
}).catch(function (error) {
console.log(error);
});
The above command returns JSON structured like this:
{
"result": {
"id": "9094fefe-3ac2-49b3-99ec-9b719331316c",
"kind": "BTC",
"txid": "7f96054005c8aab5101d48211cb23070b6a9d9b7ea25b3422de2c109eb57fad9",
"invoice": {
"id": "47ad5fa7-0754-4ba8-bc2d-1cdd0dbcddaa",
"kind": "BTC",
"created_at": "2019-02-07T22:13:15.093624+00:00",
"profile_id": "bb519172-5823-4170-a1ba-b94143eaaaea",
"address": "3Q2sdSVxqQCyYUt4NvX2y4XNmn7PRF77PZ",
"lightning": null,
"network": "mainnet",
"amount": {
"requested": {
"amount": "10.00",
"currency": "USD"
},
"invoiced": {
"amount": "0.00293528",
"currency": "BTC"
}
},
"custom_fee": null,
"min_confirmations": null,
"notes": null,
"passthrough": "{\"test\":123}"
},
"amount": {
"paid": {
"amount": "0.00293528",
"currency": "BTC",
"quotes": {
"USD": "10.00"
}
}
},
"created_at": "2019-02-07T22:13:28.681005+00:00",
"executed_at": "2019-02-07T22:21:59+00:00",
"confirmed_at": "2019-02-07T23:09:31.983230+00:00",
"confirmations": 6,
"status": "complete",
"network": "mainnet"
}
}
This endpoint retrieves a specific transaction.
HTTP Request
GET https://api.cryptochill.com/v1/transactions/<ID>/
URL Parameters
Parameter | Description |
---|---|
ID | The ID of the transaction to retrieve. |
Retrieve Confirmations
import json
payload = {
"id": [
"9094fefe-3ac2-49b3-99ec-9b719331316c",
"47ad5fa7-0754-4ba8-bc2d-1cdd0dbcddaa"
]
}
confirmations = cryptochill_api_request('transactions/confirmations', payload, 'POST')
print(json.dumps(confirmations, indent=2))
var payload = {
"id": [
"9094fefe-3ac2-49b3-99ec-9b719331316c",
"47ad5fa7-0754-4ba8-bc2d-1cdd0dbcddaa"
]
}
cryptochill_api_request('transactions/confirmations', payload, 'POST').then(function (response) {
console.log(response);
}).catch(function (error) {
console.log(error);
});
The above command returns JSON structured like this:
{
"result": [
{
"id": "9094fefe-3ac2-49b3-99ec-9b719331316c",
"confirmations": 2
},
{
"id": "47ad5fa7-0754-4ba8-bc2d-1cdd0dbcddaa",
"confirmations": 7
}
]
}
This endpoint returns confirmations for specified transaction ID(s).
HTTP Request
POST https://api.cryptochill.com/v1/transactions/confirmations/
Payload Parameters
Parameter | Description | Required |
---|---|---|
id | Array/list of transaction ID. |
Custom Fees
Example response if custom fees are applied.
{
"result": {
"id": "9094fefe-3ac2-49b3-99ec-9b719331316c",
"kind": "BTC",
"txid": "7f96054005c8aab5101d48211cb23070b6a9d9b7ea25b3422de2c109eb57fad9",
"invoice": {
"id": "cab4f4ff-6654-46c7-b22e-7d31da1eebcd",
"kind": "BTC",
"created_at": "2019-02-08T12:36:21.130435+00:00",
"profile_id": "bb519172-5823-4170-a1ba-b94143eaaaea",
"address": "3Q2sdSVxqQCyYUt4NvX2y4XNmn7PRF77PZ",
"lightning": null,
"network": "mainnet",
"amount": {
"requested": {
"amount": "100.00",
"currency": "USD"
},
"invoiced": {
"amount": "0.02967564",
"currency": "BTC"
}
},
"custom_fee": {
"amount": "0.00050000",
"currency": "BTC"
},
"min_confirmations": null,
"notes": null,
"passthrough": "{\"user_id\": 123}"
},
"amount": {
"paid": {
"amount": "0.02917564",
"currency": "BTC",
"quotes": {
"USD": "100.00"
}
},
"paid_total": {
"amount": "0.02967564",
"currency": "BTC",
"quotes": {
"USD": "101.71"
}
}
},
"created_at": "2019-02-08T12:36:21.200127+00:00",
"executed_at": null,
"confirmed_at": null,
"status": "complete",
"confirmations": 6,
"network": "testnet"
}
}
With "Custom Fees" feature merchants can charge extra fee on top of every invoice. If "fee_amount" field is specified while creating invoice, extra fee will be added to invoiced amount and later on deducted from "paid" field. In such case response will also have extra "paid_total" key with an actual transaction values and relevant quotes.
Transaction Statuses
Status | Description |
---|---|
pending | Transaction is broadcast on the Bitcoin network (0 confirmations). |
confirmed | Transaction is included in the first block (1 confirmation). |
complete | Transaction has 6+ confirmations. |
invalid | Transaction haven't been confirmed for more than hour. If it gets's confirmed later, status will be updated to "Confirmed". |
Transaction Callbacks
Callbacks provide same exact response format as in Get Transaction
API endpoint in result
field plus three extra fields specified in Callbacks Documentation.
You can view history of callbacks (if any) in CryptoChill in Transaction detail view.
Transaction Callback Statuses
Status | Description |
---|---|
transaction_pending | Any incoming transaction to invoice address (0 confirmations). |
transaction_confirmed | Any incoming transaction to invoice address (1 confirmation). |
transaction_complete | Any incoming transaction to invoice address (6+ confirmations). |
Payouts
Payouts are Bitcoin withdrawals or payments to customers, partners, etc.
List Payouts
payouts = cryptochill_api_request('payouts')
cryptochill_api_request('payouts').then(function (response) {
console.log(response);
}).catch(function (error) {
console.log(error);
});
This endpoint retrieves all payouts. Endpoint uses pagination and returns 25
payouts per page. Payouts are sorted by creation time in descending order.
HTTP Request
GET https://api.cryptochill.com/v1/payouts/
Query Parameters
Parameter | Default | Description |
---|---|---|
p | None | Page number. |
txid | None | Filter payouts by txid . |
address | None | Filter payouts by recipient address. |
reference_id | None | Filter payouts by reference_id . |
Get Payout
payout = cryptochill_api_request('payouts/42dbee1d-8659-44c3-aab2-6e414c5825a5')
cryptochill_api_request('payouts/42dbee1d-8659-44c3-aab2-6e414c5825a5').then(function (response) {
console.log(response);
}).catch(function (error) {
console.log(error);
});
This endpoint retrieves a specific payout.
HTTP Request
GET https://api.cryptochill.com/v1/payouts/<ID>/
URL Parameters
Parameter | Description |
---|---|
ID | The ID of the payout to retrieve. |
Create Payout
import json
payload = {
"profile_id": "e4e197bf-486d-4f57-a064-2d047c6cafae",
"passthrough": json.dumps({"user_id": 123}),
"reference_id": "unique-payout-id-123",
"recipients": [
{
"amount": "20",
"currency": "USD",
"address": "2N38koyyonVDAZJRV4GwnuFPxcGTymzn9HQ",
"notes": "Notes 1"
},
{
"amount": "10",
"currency": "GBP",
"address": "2MzCZNNDrmUB55LzdXnmdaXH2h2nJJ9EhrL",
"notes": "Notes 2"
},
{
"amount": "0.01",
"currency": "BTC",
"address": "2NC3zgngjjRWR7kbKzKYYPR2jpWh3QZHRML",
"notes": "Notes 3"
}
]
}
payout = cryptochill_api_request('payouts', payload, 'POST')
print(json.dumps(payout, indent=2))
var payload = {
"profile_id": "e4e197bf-486d-4f57-a064-2d047c6cafae",
"passthrough": JSON.stringify({"user_id": 123}),
"reference_id": "unique-payout-id-123",
"recipients": [
{
"amount": "20",
"currency": "USD",
"address": "2N38koyyonVDAZJRV4GwnuFPxcGTymzn9HQ",
"notes": "Notes 1"
},
{
"amount": "10",
"currency": "GBP",
"address": "2MzCZNNDrmUB55LzdXnmdaXH2h2nJJ9EhrL",
"notes": "Notes 2"
},
{
"amount": "0.01",
"currency": "BTC",
"address": "2NC3zgngjjRWR7kbKzKYYPR2jpWh3QZHRML",
"notes": "Notes 3"
}
]
}
cryptochill_api_request('payouts', payload, 'POST').then(function (response) {
console.log(response);
}).catch(function (error) {
console.log(error);
});
JSON response for Create Payout endpoint:
{
"result": {
"id": "2f065e32-8b11-4081-b302-57f9f9dbd2e4",
"kind": "BTC",
"txid": "7efa4998d0b6d62c13154e53bed0b6c5283c73ac5412ce09c2ac437be031fb9d",
"created_at": "2019-02-11T03:04:51.113794+00:00",
"executed_at": "2019-02-11T03:05:15.110291+00:00",
"profile_id": "e4e197bf-486d-4f57-a064-2d047c6cafae",
"wallet_id": "9ebdef36-71dd-4fdf-b02d-e5f836b4052f",
"confirmations": 0,
"status": "new",
"network": "testnet",
"amount": {
"total": "0.01901596",
"network_fee": "0.00001000"
},
"network_fee_pays": "merchant",
"network_fee_preset": "normal",
"network_fee": 5,
"passthrough": "{\"user_id\": 123}",
"reference_id": "unique-payout-id-123",
"recipients": [
{
"id": "912c9225-eb7f-4697-a5ab-7d28acfb9168",
"address": "2N38koyyonVDAZJRV4GwnuFPxcGTymzn9HQ",
"amount": {
"requested": {
"amount": "20.00000000",
"currency": "USD"
},
"received": {
"amount": "0.00546744",
"currency": "BTC"
}
},
"custom_fee": null,
"notes": "Notes 1"
},
{
"id": "d49d2ef4-6613-4870-9fcf-6becce855761",
"address": "2MzCZNNDrmUB55LzdXnmdaXH2h2nJJ9EhrL",
"amount": {
"requested": {
"amount": "10.00000000",
"currency": "GBP"
},
"received": {
"amount": "0.00353852",
"currency": "BTC"
}
},
"custom_fee": null,
"notes": "Notes 2"
},
{
"id": "b827813f-389e-457e-81c5-13cd1cf49d27",
"address": "2NC3zgngjjRWR7kbKzKYYPR2jpWh3QZHRML",
"amount": {
"requested": {
"amount": "0.01000000",
"currency": "BTC"
},
"received": {
"amount": "0.01000000",
"currency": "BTC"
}
},
"custom_fee": null,
"notes": "Notes 3"
}
]
}
}
This endpoint creates a payout. Response is identical to Get Payout endpoint response.
HTTP Request
POST https://api.cryptochill.com/v1/payouts/
Payload Parameters
Parameter | Description | Required |
---|---|---|
kind | Available values:BTC – Bitcoin On-chain payout (Default).BTC_LIGHTNING_TO_BTC – Lightning Network to On-Chain payout.BTC_LIGHTNING_TO_LIGHTNING – Lightning Network to Lightning Network payout.LTC – Litecoin On-chain payout. |
No |
profile_id | Profile ID for settings, callbacks and wallet selection if wallet_id not specified. |
Yes |
wallet_id | Wallet ID for funds selection. If not specified, default profile wallet is used. | No |
passthrough | String. Meta-data you wish to store with the payout. If provided and no reference_id is specified, must be a unique value to avoid accidental duplicate payouts. Will be sent alongside all callbacks associated with the payout. |
No |
reference_id | String. Unique reference ID. Field is being indexed and is useful for lookups. If provided must be a unique value to avoid accidental duplicate payouts. Will be sent alongside all callbacks associated with the payout. | No |
recipients | Array/list of recipient objects. | Yes |
network_fee_pays | Who pays network fee. Available values: merchant (default) or recipient . In case of recipient value network fee will be deducted from first recipient. |
No |
network_fee_preset | Network fee preset. Available values: high , normal (default) , economy . |
No |
network_fee | Custom network fee in satoshi/byte. Integer. | No |
Recipient Object Parameters
Parameter | Description | Required |
---|---|---|
amount | Quoted decimal payment amount. Optional for BTC_LIGHTNING_TO_LIGHTNING kind. |
Yes |
currency | Currency for the specified payment amount. Available values: USD, BTC, EUR, GBP, AUD, CHF. | Yes |
address | Address of the recipient or payment request for kind BTC_LIGHTNING_TO_LIGHTNING . |
Yes |
fee_amount | Custom fee amount that will be deducted from "received" amount. | No |
fee_currency | Custom fee currency. Available values: BTC. | No |
Payout Confirmations
import json
payload = {
"id": [
"9094fefe-3ac2-49b3-99ec-9b719331316c",
"47ad5fa7-0754-4ba8-bc2d-1cdd0dbcddaa"
]
}
confirmations = cryptochill_api_request('payouts/confirmations', payload, 'POST')
print(json.dumps(confirmations, indent=2))
var payload = {
"id": [
"9094fefe-3ac2-49b3-99ec-9b719331316c",
"47ad5fa7-0754-4ba8-bc2d-1cdd0dbcddaa"
]
}
cryptochill_api_request('payouts/confirmations', payload, 'POST').then(function (response) {
console.log(response);
}).catch(function (error) {
console.log(error);
});
The above command returns JSON structured like this:
{
"result": [
{
"id": "9094fefe-3ac2-49b3-99ec-9b719331316c",
"confirmations": 2
},
{
"id": "47ad5fa7-0754-4ba8-bc2d-1cdd0dbcddaa",
"confirmations": 7
}
]
}
This endpoint returns confirmations for specified payout ID(s).
HTTP Request
POST https://api.cryptochill.com/v1/payouts/confirmations/
Payload Parameters
Parameter | Description | Required |
---|---|---|
id | Array/list of payout ID. |
Payout Statuses
Status | Description |
---|---|
draft | Either payout was created manually in the app and is not yet approved or payout was made by an API, but the payout amount was larger than "Max Payout" value for current API key - in such case requires manual approval in the app. |
new | Payout is just created and is awaiting further processing. |
pending | Payout transaction is broadcast on the Bitcoin network (0 confirmations). |
confirmed | Payout transaction is included in the first block (1 confirmation). |
complete | Payout transaction has 6+ confirmations. |
invalid | Payout transaction haven't been confirmed for more than hour. If it gets's confirmed later, status will be updated to "Confirmed". |
Payout Callbacks
Callbacks provide same exact response format as in Get Payout
API endpoint in result
field plus three extra fields specified in Callbacks Documentation.
You can view history of callbacks (if any) in CryptoChill in Payout detail view.
Payout Callback Statuses
Status | Description |
---|---|
payout_pending | Payment transaction is broadcast on the Bitcoin network (0 confirmations). |
payout_confirmed | Payout transaction is included in the first block (1 confirmation). |
payout_complete | Payout transaction has 6+ confirmations. |
payout_failed | Payout has failed. |
Profiles
Profiles define which wallet will be used for address generation and to which callback URL related events should be sent.
List Profiles
profiles = cryptochill_api_request('profiles')
cryptochill_api_request('profiles').then(function (response) {
console.log(response);
}).catch(function (error) {
console.log(error);
});
The above command returns JSON structured like this:
{
"result": [
{
"id": "<id>",
"name": "Production"
},
{
"id": "<id>",
"name": "Testnet"
}
]
}
This endpoint retrieves all profiles.
HTTP Request
GET https://api.cryptochill.com/v1/profiles/
Get Profile
profiles = cryptochill_api_request('profiles/123')
cryptochill_api_request('profiles/123').then(function (response) {
console.log(response);
}).catch(function (error) {
console.log(error);
});
The above command returns JSON structured like this:
{
"result": {
"id": "<id>",
"name": "Production"
}
}
This endpoint retrieves a specific profile.
HTTP Request
GET https://api.cryptochill.com/v1/profiles/<ID>/
URL Parameters
Parameter | Description |
---|---|
ID | The ID of the profile to retrieve |
Exchange Rates
Get latest exchange rates between fiat and cryptocurrencies.
List Rates
rates = cryptochill_api_request('exchange-rates')
cryptochill_api_request('exchange-rates').then(function (response) {
console.log(response);
}).catch(function (error) {
console.log(error);
});
The above command returns JSON structured like this:
{
"result": [
{
"id": "united-states-dollar",
"kind": "fiat",
"symbol": "USD",
"rate_usd": "1",
"rate_btc": "0.000292111117128",
"sign": "$"
},
{
"id": "euro",
"kind": "fiat",
"symbol": "EUR",
"rate_usd": "1.1424784928423721",
"rate_btc": "2996.4282380088874310",
"sign": "€"
},
{
"id": "bitcoin",
"kind": "crypto",
"symbol": "BTC",
"rate_usd": "3423.3548172707183421",
"rate_btc": "1",
"sign": "₿"
}
]
}
Get all exchange rates:
HTTP Request
GET https://api.cryptochill.com/v1/exchange-rates/
Get Rate
Get exchange rate for specific fiat currency only.
rates = cryptochill_api_request('exchange-rates/EUR')
cryptochill_api_request('exchange-rates/EUR').then(function (response) {
console.log(response);
}).catch(function (error) {
console.log(error);
});
The above command returns JSON structured like this:
{
"result": {
"id": "euro",
"kind": "fiat",
"symbol": "EUR",
"rate_usd": "1.1424784928423721",
"rate_btc": "2996.4282380088874310",
"sign": "€"
}
}
HTTP Request
GET https://api.cryptochill.com/v1/exchange-rates/<SYMBOL>/
URL Parameters
Parameter | Description |
---|---|
SYMBOL | Symbol of the currency to retrieve |
Callbacks
Callbacks are POST
(as JSON
encoded request body) requests made by CryptoChill to URL endpoint specified in Profile that was used for related invoice creation.
Callback expects HTTP 200
OK success status response code. For any other status code or timeout it will try to reach endpoint again with exponential time increase between retries. If after 72 hours
endpoint will be still unreachable callback sender will stop trying.
You can view history of callbacks in CryptoChill app under every instance that have callbacks.
Callbacks Verification
import hashlib
import hmac
import json
# You will find your callback token under Settings
CALLBACK_TOKEN = 'your_callback_token'
# You can reuse same method used in API auth signature generation
def encode_hmac(key, msg, digestmod=hashlib.sha256):
return hmac.new(key.encode(), msg=msg, digestmod=digestmod).hexdigest()
# Decode request json body
payload = json.loads(request.body)
# Get signature and callback_id fields from provided data
signature = payload['signature']
callback_id = payload['callback_id']
# Compare signatures
is_valid = signature == encode_hmac(CALLBACK_TOKEN, callback_id.encode())
assert is_valid, 'Failed to verify CryptoChill callback signature.'
# Debug callback data
print(json.dumps(payload, indent=2))
const Base64 = require('js-base64').Base64;
const crypto = require('crypto');
// You will find your callback token under Settings
const CALLBACK_TOKEN = 'your_callback_token';
// You can reuse same method used in API auth signature generation
function encode_hmac(key, msg) {
return crypto.createHmac('sha256', key).update(msg).digest('hex');
}
// Decode request json body
var payload = JSON.parse(request.body);
// Get signature and callback_id fields from provided data
const signature = payload['signature'];
const callback_id = payload['callback_id'];
// Compare signatures
const is_valid = signature === encode_hmac(CALLBACK_TOKEN, callback_id);
if(!is_valid) {
throw new Error('Failed to verify CryptoChill callback signature.');
}
// Debug callback data
console.log(payload);
To verify callback and make sure it really comes from CryptoPanic you must use Callback Token which you can find in CryptoChill app under Settings > API Keys.
Always verify if signature provided in callback POST data matches the one you generate on your own by signing callback_id
value with callback_token
using following hashing algorithm:
signature = hex(HMAC_SHA256(<callback_id>, key=<callback_token>))
Callbacks Response
All callbacks have these fields in common:
Key | Meaning |
---|---|
callback_id | Unique callback ID. If callback fails to reach endpoint, it will retry with the same ID. |
callback_status | Callback status identifying specific event. |
signature | CryptoChill signature for verification. |
For event specific response documentation see Callback section under specific endpoint.
Errors
Error payload
Example of error response:
{
"result": "error",
"reason": "ObjectNotFound",
"message": "Object by specified ID not found"
}
In the event of an error, a non-200 error code will be returned, and the response body will be a json object with three fields:
result
– which will always be "error".reason
– which will be one of the string constants.message
– a human-readable string with additional error information.
HTTP error codes
Error Code | Meaning |
---|---|
400 | Bad Request – Your request is invalid. |
401 | Unauthorized – Your API key or signature is wrong. |
403 | Forbidden – Not enough permissions. |
404 | Not Found – The specified page could not be found. |
405 | Method Not Allowed – You tried to access endpoint with an invalid method. |
500 | Internal Server Error – We had a problem with our server. |
503 | Service Unavailable – We're temporarily offline for maintenance. |