Bitcoin-Api.io
About
The Bitcoin-Api.io professional grade API lets you easily add bitcoin to your websites and apps. Using a token, you can effortlessly incorporate bitcoin deposit and withdraw functionality into your tech.
Main Sections
NodeJs Driver
Example
'use strict';
const BitcoinApi = require( 'bitcoin-api' );
const bitcoinApi = new BitcoinApi({
testnetToken: 'thapntygr8prv'
});
(async () => {
try {
const {
balanceData: { amount }
} = await bitcoinApi.getTokenInfo();
// logs current balance
console.log( 'Balance:', amount );
// withdraws 0.00004 BTC
await bitcoinApi.withdraw({
amount: 0.00004,
address: 'mgXi9VCAmwaEGszk5yhqkigptTVQM33uhx',
});
}
catch( err ) {
console.log( 'err:', err );
}
})();Install
npm install bitcoin-api --save
Setup
'use strict';
const BitcoinApi = require( 'bitcoin-api' );
const bitcoinApi = BitcoinApi({
livenetMode: false,
// optional: defaults to false
testnetToken: 'xxcsddfksdjaksld',
livenetToken: 'yycsddfksdjaksld'
// one of testnetToken or livenetToken is required
});Usage
.getTokenInfo
(async () => {
const tokenInfo = await bitcoinApi.getTokenInfo();
console.log( 'Token Info:', JSON.stringify( tokenInfo, null, 4 ) );
/*
Logs:
Token Info: {
"isActivated": true,
"balanceData": {
"amount": 0.002,
"status": "normal"
}
}
*/
})();.createOrGetAddress
(async () => {
const address = await bitcoinApi.createOrGetAddress();
console.log( 'Bitcoin Address:', address );
/*
logs:
Bitcoin Address: 3AfV9QQQTgtCH6YEjBpDTyH5sswgGD5MLp
note:
createOrGetAddress will return null
when no fresh addresses are available
*/
}();.getFeeData
(async () => {
const feeData = await bitcoinApi.getFeeData();
console.log( 'Fee Data:', JSON.stringify( feeData, null, 4 ) );
/*
logs:
Fee Data: {
"fee": 0.0000001
}
*/
}();.withdraw
(async () => {
await bitcoinApi.withdraw({
amount: 0.002,
address: '3AfV9QQQTgtCH6YEjBpDTyH5sswgGD5MLp',
includeFeeInAmount: false
});
/*
withdraws 0.002 BTC to 3AfV9QQQTgtCH6YEjBpDTyH5sswgGD5MLp
note:
includeFeeInAmount is optional
when set to true, the fee will automatically
be deducted from the amount
*/
}();Raw API Documentation
Table of Contents
Requests
Base Url
Testnet:
https://api-bitcoin.io/v3
Livenet:
https://bitcoin-api.io/v3
(livenet API currently not enabled)
Public Endpoints
Public Endpoints can be accessed using HTTPS requests with the following headers:
// HTTP headers to add to make requests to Public Endpoints
{
"Content-Type": "application/json"
}Tokens
Tokens are used to make authorized requests to the Bitcoin-Api.io API. These authorized requests allow you to access and to control your bitcoin. A token is a key that gives you access to your bitcoin, bitcoin addresses, withdraws, and any other resources associated with that token. It is very important that you keep your token secret and secure in order to protect your bitcoins and any token-associated data.
General-Token Endpoints
General-Token Endpoints are endpoints that must be accessed using a token in the header. You first acquire a token by making a request to the /tokens POST public endpoint.
Once you have a token, you can add it to your HTTPS request header like below to make authorized requests to General-Token Endpoints:
// HTTP headers to add to make requests to General-Token Endpoints
{
"Content-Type": "application/json",
"Token": "YOUR_TOKEN_GOES_HERE_INSTEAD_OF_THIS_TEXT"
}Activated-Token Endpoints
As the name suggests, an Activated-Token Endpoint can only be accessed using an Activated-Token. To activate your token, use the appropriate link below:
Activate your testnet token with the following link:
Testnet Token Activator (for Api-Bitcoin.io)
Activate your livenet token with the following link:
Livenet Token Activator (for Bitcoin-Api.io)
(not enabled: the livenet site will be active in the future)
Once you have an Activated-Token, you can add it to your HTTPS request header like below to make authorized requests to token-only endpoints:
{
"Content-Type": "application/json",
"Token": "YOUR_ACTIVATED-TOKEN_GOES_HERE_INSTEAD_OF_THIS_TEXT"
}Responses
All responses, success or error, should always respond with a 200 status code in the actual HTTPS response.
This implies that any non-200 status code responses should be considered unexpected internal server errors or the request itself was invalid (e.g. accidentally using the wrong HTTP method).
Successful Responses
Requests that executed successfully will return a response in the following form:
{
"statusCode": 200, // number (200-299)
"body": {
"key_1": "value_1",
"key_2": "value_2",
"key_3": "value_3",
...,
"key_i": "value_i",
...,
"key_n": "value_n"
}, // object
}Error Responses
Assuming the request was properly formed and there were no internal server errors, as explained above, the HTTPS request itself will respond with a 200 status code although the contents of that response will be in the following form:
{
"statusCode": 400 || 500, // number (400-599)
"isError": true,
"message": "the error message will be here instead of this text", // string
}Resources
/tokens
POST - Create Token
Create a new token. Tokens provide access to your bitcoins and associated resources by authorizing token-only requests.
Authorization
Public Endpoint
Request Body Example
{}Response Body Example
{
"statusCode": 200,
"body": {
"token": "asjfhnsdlkjfhdskljhfskdljfhsdjkfsdkjfhnsdlsdf..."
}
}GET - Get Token Info
This endpoint gets info associated with a token.
Authorization
General-Token Endpoint
Response Body Example
{
"statusCode": 200,
"body": {
"isActivated": false,
"balanceData": {
"amount": 0.0005,
"status": "normal"
}
}
}- For the balance data (
body.balanceData) returned in the response, there is astatusvalue associated with it. The value will either be"normal"or"transformation". If the value is in the"transformation"state, that means a withdraw is currently being processed.
PUT - Update Token Value
This endpoint updates your token's value. Your old token's value becomes invalid when you update that token's value.
Authorization
General-Token Endpoint
Request Body Example
{}Response Body Example
{
"statusCode": 200,
"body": {
"token": "2asjfhnsdlkjfhdskljhfskdljfhsdjkfsdkjfhnsdlsdf..."
}
}/addresses
POST - Create or Get Bitcoin Address
This endpoint creates a new bitcoin address that can
be used to deposit bitcoins. A new address will be generated
once the old one has bitcoin sent to it.
If the address value is null,
there are currently no new addresses available and you
must try again later.
Authorization
Activated-Token Endpoint
Request Body Example
{}Response Body Example
{
"statusCode": 200,
"body": {
"address": "3AfV9QQQTgtCH6YEjBpDTyH5sswgGD5MLp",
"timeOfExpiry": 1588611713247
}
}More Info:
The balance associated with your token will be automatically updated after your bitcoin deposit transaction has at least 6 confirmations on the bitcoin network. You can retrieve your bitcoin balance using the /tokens GET General-Token Endpoint.
If you don't deposit bitcoin to your address before it expires, that address will be reclaimed by Bitcoin-Api meaning you will not be able to access any bitcoin sent to that address. Bitcoin-Api will never expire an address that already has bitcoin sent to it.
/fee-data
GET - Get Fee Data
This endpoint gets an estimate of the current fee that's added to the withdraw amount. This fee is only used to cover the bitcoin network fees.
Authorization
Public Endpoint
Response Body Example
{
"statusCode": 200,
"body": {
"fee": 0.000002
}
}More Info:
This fee estimate is subject to change according to the bitcoin network. This fee estimate provides an estimation of the maximum amount of bitcoin that will be used by the bitcoin network to send bitcoin to the desired address. If the actual fee demanded by the bitcoin network is less than the current fee estimate, whatever fee is not used while performing a withdraw will be refunded shorty after the withdraw has been performed.
/withdraws
POST - Do Withdraw
This endpoint withdraws bitcoin associated with your token.
Authorization
Activated-Token Endpoint
Request Body Example
{
"amount": 0.00004, // 0.00004 is the min withdraw amount
"address": "3AfV9QQQTgtCH6YEjBpDTyH5sswgGD5MLp",
"includeFeeInAmount": false // optional, defaults to false
}Response Body Example
{
"statusCode": 200,
"body": {}
}Glossary
-
Activated-Token Endpoint: an API endpoint that requires an Activated-Token set in the request headers in order to authorize the request. See the Activated-Token Endpoint request section for details on how to make Activated-Token requests.
-
API: an application programming interface (API), in the context of Bitcoin-Api, refers to a collection of access points (called API endpoints) which are used to access and control your bitcoins. Check out this article on bitcoin APIs and regular APIs for a more detailed explanation of what bitcoin APIs and regular APIs are and how they function.
-
Endpoint (or API Endpoint): an endpoint is a url with an HTTP method (e.g. GET, POST) that can be accessed via HTTPS requests. Endpoints are the main communication channel of Bitcoin-Api and form the basis for all operations in the API.
-
Public Endpoint: an API endpoint that is accessible for everyone without any token authorization required. See the Public Endpoint Request section for details on how to make public endpoint requests.
Bitcoin-Api.io - Bitcoin as a service
"#BaaS is #Bitcoin #API."
