Bitbond API

The Bitbond API gives you programmatical access to Bitbond services. In order to use the API for global bitcoin peer-to-peer lending and investing you need to create an OAuth application. To do so either log in if you already have an account with Bitbond or sign up here for free.

Authentication

The Bitbond API is using standard Oauth2 authentication. To create the required API keys follow these steps:

  1. Log in into your account (log in or sign up)

  2. Go to Settings -> API applications

  3. Add a new API application

  4. Use the provided API keys to connect to the API

  5. When authorizing the user, please include an “api” scope, so the final URL will look like:

https://www.bitbond.com/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&response_type=code&scope=api

Urls

The Oauth2 authorization url is: https://www.bitbond.com/oauth/authorize

The Oauth2 token url is: https://www.bitbond.com/oauth/token

Access and refresh tokens

The access tokens expire after 2 hours. You can use the refresh token to renew your access.

Authentication flow example

  1. The user clicks on a authorization url generated for your application:
https://www.bitbond.com/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&response_type=code&scope=api
  1. The user is asked if they want to authorize your application

  2. If the user agrees, he will be redirected to the REDIRECT_URI you have specified, this GET request will include a query parameter called “code” which is the authorization code

  3. Your application makes a POST request to the https://www.bitbond.com/oauth/token endpoint with the following POST parameters:

client_id = CLIENT_ID
client_secret = CLIENT_SECRET
code = The code you have received in step 3
grant_type = authorization_code
redirect_uri = REDIRECT_URI

and the response will be:

{"access_token":"ACCESS_TOKEN", "token_type":"bearer","expires_in":7200,"refresh_token":"76ba4c5c75c96f6087f58a4de10be6c00b29ea1ddc3b2022ee2016d1363e3a7c","scope":"api"}
  1. You can use the API now, by including the access_token as a AUTHORIZATION header: AUTHORIZATION: Bearer ACCESS_TOKEN or GET parameter: access_token=ACCESS_TOKEN

  2. When the token expires, you can refresh the token by making a POST request to https://www.bitbond.com/oauth/token with the following POST params:

client_id = CLIENT_ID
client_secret = CLIENT_SECRET
refresh_token = REFRESH_TOKEN
grant_type = refresh_token

You also need to include the last expired access token as specified previously in section 5.

Remember to store the new access token!

Client libraries

Ruby

The ruby client library is available from: https://github.com/bitbond/bitbond-ruby

For a usage example, see here: https://github.com/bitbond/bitbond-ruby/tree/master/example

Data format

Timestamps

Timestamps and dates are stored in the ISO8601 format. Here is an example timestamp: “2015-09-24T17:16:29.649Z”

Monetary values

Monetary values are represented by an object of the form:

"amount": {
   "units": "1000000",
   "currency": "usd"
 }

Each currency has 8 decimal unit precision, this also applies to usd.

For example, 1 usd would be represented as:

"amount": {
   "units": "100000000",
   "currency": "usd"
 }

Units is always a string, since with 8 decimal places you can easily overflow int values.

Loan statuses

Here is a list of loan statuses, and their meaning:

  • in_funding - a loan that is listed and can be invested in

  • funded - a loan that received funding and had no payment due, yet

  • current - a funded loan where all payments that have been due to date have been completed

  • fully_paid - a loan that is fully paid

  • late_30 - a loan where one or more payments are between 3 and 30 days overdue

  • late_90 - a loan where one or more payments are between 31 and 90 days overdue

  • defaulted - a loan where one or more payments are over 90 days overdue

  • canceled - a loan which got canceled during the auction and therefore was never funded

  • expired - a loan which didn’t get funded during the auction and therefore expired

  • charged_off - a defaulted loan where all collection activities have been terminated

Payment statuses

Here is a list of payment statuses and their meaning:

  • scheduled - a future loan payment

  • paid_out - initial pay out of the loan amount to the borrower

  • paid - a payment that has been paid on time

  • paid_late - a payment that has been paid late

  • in_grace_period - a payment that has been due and is in the 3 day grace period

  • late_thirty - a payment that is overdue for more than 3 and up to 30 days

  • late_ninety - a payment that is overdue for more than 30 and up to 90 days

  • defaulted - a payment that is overdue for more than 90

Base currencies

Currently Bitbond supports the following base currencies

  • usd

  • btc

Nominal interest rate

Nominal interest rate is shown in basis points.

One basis point equals to 1/100 of a percent, or 0.0001 of a value.

Investments

Shows information about the loans in which the current user has invested, grouped by base currency.

Investments

GET https://www.bitbond.com/api/v1/investments?status[]=in_funding&base_currency[]=btc&rating[]=A&term[]=term_6_weeks
Responses200
Headers
Content-Type: application/json
Body
{
    "investments": [{
        "code": "2PKE3W4WWD",
        "status": "FULLY_PAID",
        "base_currency": "usd",
        "rating": "B",
        "term": "term_6_weeks",
        "country_code": "US",
        "amount_funded": {
          "units": "100000000",
          "currency": "usd"
        },
        "amount_invested": {
          "units": "100000000",
          "currency": "usd"
        },
        "interest_received": {
          "units": "0",
          "currency": "usd"
        },
        "outstanding_principal": {
          "units": "0",
          "currency": "usd"
        },
        "overdue_principal": {
          "units": "0",
          "currency": "usd"
        },
        "overdue_interest": {
          "units": "0",
          "currency": "usd"
        },
        "funded_at": "2016-01-07T17:40:17.676Z",
        "next_payment_due_at": "2016-03-01T12:00:00.000Z",
        "last_payment_due_at": "2016-09-01T12:00:00.000Z",
        "note_count": 1,
        "nominal_interest_rate": 1000 //in basis points
        "accounts": ["Primary"]
    }]
}

List investments in given base currency
GET/investments{?status[],base_currency[],rating[],term[]}

URI Parameters
HideShow
status[]
enum[string] array (optional) Example: in_funding

The status of the investment

Choices: in_funding funded current fully_paid late_30 late_90 defaulted canceled expired charged_off

base_currency[]
enum[string] array (optional) Example: btc

base currency of the investment

Choices: btc usd

rating[]
enum[string] array (optional) Example: A

rating of the borrower at time of investment funding

Choices: A B C D E F

term[]
enum[string] array (optional) Example: term_6_weeks

term of the investment

Choices: term_6_weeks term_6_months term_12_months term_36_months term_60_months


Investment details

GET https://www.bitbond.com/api/v1/investments/'2PKE3W4WWD'
Responses200
Headers
Content-Type: application/json
Body
{
    "investment": {
        "code": "2PKE3W4WWD",
        "status": "FULLY_PAID",
        "base_currency": "usd",
        "rating": "B",
        "term": "term_6_weeks",
        "country_code": "US",
        "amount_funded": {
          "units": "100000000",
          "currency": "usd"
        },
        "amount_invested": {
          "units": "100000000",
          "currency": "usd"
        },
        "interest_received": {
          "units": "0",
          "currency": "usd"
        },
        "outstanding_principal": {
          "units": "0",
          "currency": "usd"
        },
        "overdue_principal": {
          "units": "0",
          "currency": "usd"
        },
        "overdue_interest": {
          "units": "0",
          "currency": "usd"
        },
        "funded_at": "2016-01-07T17:40:17.676Z",
        "next_payment_due_at": "2016-03-01T12:00:00.000Z",
        "last_payment_due_at": "2016-09-01T12:00:00.000Z",
        "note_count": 1,
        "nominal_interest_rate": 1000 //in basis points
        "accounts": ["Primary"]
    }
}

Show investment details
GET/investments/{code}

URI Parameters
HideShow
code
string (required) Example: '2PKE3W4WWD'

the code identifying the loan / investment


Profile

Public user profile information

Profile

Detailed profile information.

Employment details / payment history only exists for users who received a borrower rating.

Identities are external accounts that the borrower connected with Bitbond in order to signal their creditworthiness.

GET https://www.bitbond.com/api/v1/profiles/2FWVQJ4KJJ
Responses200
Headers
Content-Type: application/json
Body
{
  "profile": {
    "code": "2D85HS31S1",
    "username": "testuser",
    "bio": "bio..",
    "rating": "D",
    "region": "JAWA BARAT, Indonesia",
    "loans": [
      "2FWVQJ4KJJ",
      "3FWVQJ4KJJ"
    ],
    "payment_history": {
      "on_time": 0,
      "late": 0,
      "overdue": 0
    },
    "employment_details": {
      "employment_type": "salaried",
      "industry": "financial and insurance activities",
      "monthly_income": {
        "units": "1000000000000",
        "currency": "usd"
      }
    },
    "identities": [
      {
        "provider": "linkedin"
      },
      {
        "provider": "ebay"
      }
    ],
    "investments": [
      {
        "loan_code": "2D85HT31S8",
        "amount": {
          "units": "1000000",
          "currency": "btc"
        }
      }
    ]
  }
}

Show profile
GET/profiles/{handle}

URI Parameters
HideShow
handle
string (required) Example: 2FWVQJ4KJJ

The handle uniquely identifying the user for which we want to view the profile, or me if you want to retrieve the profile of currently logged in user


Accounts

The current user’s account information, including balance, wallet address and transaction history.

Funds

GET https://www.bitbond.com/api/v1/accounts/primary
Responses200
Headers
Content-Type: application/json
Body
{
  "account": {
    "account_type": "primary",
    "balance": {
      "units": "100000000",
      "currency": "btc"
    },
    "wallet_address": "mvziXhUeFfiT8wM8vn3BgKaHqFiDYCNPou",
    "transactions": [
      {
        "transaction_type": "place_bid",
        "created_at": "2016-01-07T18:04:45.570Z",
        "amount": {
          "units": "1000000",
          "currency": "btc"
        }
      }
    ]
  }
}

Show funds information
GET/accounts/{account_type}

URI Parameters
HideShow
account_type
string (required) Example: primary

The account type

Choices: primary auto_invest


Loans

Show information about all loans from Bitbond.

Loans

GET https://www.bitbond.com/api/v1/loans?status[]=in_funding&base_currency[]=btc&rating[]=A&term[]=term_6_weeks&page=1
Responses200
Headers
Content-Type: application/json
Body
{
  "loans": [{
      "code": "2D85JG31WN",
      "issued_at": "2015-07-27T15:16:48.786Z",
      "funded_at": "2015-09-18T11:46:01.075Z",
      "auction_expires_at": "2015-12-18T11:40:43.030Z",
      "status": "funded",
      "rating": "C",
      "base_currency": "usd",
      "term": "term_60_months",
      "exchange_rate": "292.97",
      "country_code": "CA",
      "amount": {
        "units": "50000000",
        "currency": "btc"
      },
      "amount_funded": {
        "units": "14648500000",
        "currency": "usd"
      },
      "amount_funded_satoshi": {
        "units": "50000000",
        "currency": "btc"
      },
      "issuer_code": "2D85HS31S5",
      "purpose": "renovation",
      "description": "I want to renovate",
      "nominal_interest_rate": 1000,
      "comments_count": 1
  }
}

List loans
GET/loans{?status[],base_currency[],rating[],term[],page}

URI Parameters
HideShow
status[]
enum[string] array (optional) Example: in_funding

The status of the loan

Choices: in_funding funded current fully_paid late_30 late_90 defaulted canceled expired charged_off

base_currency[]
enum[string] array (optional) Example: btc

base currency of the loan

Choices: btc usd

rating[]
enum[string] array (optional) Example: A

rating of the borrower at time of loan funding

Choices: A B C D E F

term[]
enum[string] array (optional) Example: term_6_weeks

term of the loan

Choices: term_6_weeks term_6_months term_12_months term_36_months term_60_months

page
integer (optional) Example: 1

Loan details

Show loan details including all loan payments and loan comments.

GET https://www.bitbond.com/api/v1/loans/2FWVQJ4KJJ
Responses200
Headers
Content-Type: application/json
Body
{
  "loan": {
    "code": "2D85JG31WN",
    "issued_at": "2015-07-27T15:16:48.786Z",
    "funded_at": "2015-09-18T11:46:01.075Z",
    "auction_expires_at": "2015-12-18T11:40:43.030Z",
    "status": "funded",
    "rating": "C",
    "base_currency": "usd",
    "term": "term_60_months",
    "exchange_rate": "292.97",
    "country_code": "CA",
    "amount": {
      "units": "50000000",
      "currency": "btc"
    },
    "amount_funded": {
      "units": "14648500000",
      "currency": "usd"
    },
    "amount_funded_satoshi": {
      "units": "50000000",
      "currency": "btc"
    },
    "issuer_code": "2D85HS31S5",
    "purpose": "renovation",
    "description": "I want to go pro",
    "nominal_interest_rate": 1000,
    "comments_count": 1,
    "payments": [
      {
        "bond_code": "2D85JG31WN",
        "number": 0,
        "due_at": "2015-09-18T11:46:01.075Z",
        "received_at": "2015-09-18T11:46:02.261Z",
        "status": "paid_out",
        "failed_count": 0,
        "exchange_rate": "292.97",
        "outstanding_principal_per_note": {
          "units": "292970000",
          "currency": "usd"
        },
        "interest_payment_per_note": {
          "units": "0",
          "currency": "usd"
        },
        "principal_payment_per_note": {
          "units": "0",
          "currency": "usd"
        },
        "total_payment_per_note": {
          "units": "291505150",
          "currency": "usd"
        }
      },
      {
        "bond_code": "2D85JG31WN",
        "number": 1,
        "due_at": "2015-11-01T11:46:00.000Z",
        "received_at": null,
        "status": "scheduled",
        "failed_count": 0,
        "exchange_rate": "292.97",
        "outstanding_principal_per_note": {
          "units": "290298319",
          "currency": "usd"
        },
        "interest_payment_per_note": {
          "units": "3553066",
          "currency": "usd"
        },
        "principal_payment_per_note": {
          "units": "2671681",
          "currency": "usd"
        },
        "total_payment_per_note": {
          "units": "6224747",
          "currency": "usd"
        }
      },
    ],
    "comments": [
      {
        "created_at": "2015-07-31T15:07:07.182Z",
        "user_code": "2D85HS31S3",
        "body": "test"
      }
    ]
  }
}

Show loan details
GET/loans/{code}

URI Parameters
HideShow
code
string (required) Example: 2FWVQJ4KJJ

The code uniquely identifying the loan


POST https://www.bitbond.com/api/v1/loans/2FWVQJ4KJJ/bids
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "amount": 0.1
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "amount": {
      "type": "number",
      "description": "The bid amount in btc, must be smaller or equal to the amount left\nand larger or equal to the account balance.\n"
    }
  },
  "required": [
    "amount"
  ]
}
Responses200400
Headers
Content-Type: application/json
Body
{}
Headers
Content-Type: application/json
Body
{
  "errors": {
    "amount": "Amount must be bigger than 0.01 btc"
  }
}

Place bid
POST/loans/{code}/bids

This endpoint allows placing bids on currently listed loans. Only loans with status ‘in_funding’ can be invested in. Bids can not be cancelled.

URI Parameters
HideShow
code
string (required) Example: 2FWVQJ4KJJ

The code uniquely identifying the loan


Webhooks

You can create a webhook using the API. The following notifications are supported:

  • New loan notification

    • Request (application/json)

      {
            "user_code": "2D85HS31S1",
            "callback_url": "https://www.callback.co/callback",
            "event": {
               "event_type": "LOAN_CREATED",
               "code": "2PKE3W4WWD"
            }
        }
  • Loan cancelled notification

    • Request (application/json)

      {
            "user_code": "2D85HS31S1",
            "callback_url": "https://www.callback.co/callback",
            "event": {
               "event_type": "LOAN_CANCELLED",
               "code": "2PKE3W4WWD"
            }
        }
  • Loan expired notification

    • Request (application/json)

      {
            "user_code": "2D85HS31S1",
            "callback_url": "https://www.callback.co/callback",
            "event": {
               "event_type": "LOAN_EXPIRED",
               "code": "2PKE3W4WWD"
            }
        }
  • Account balance changed

    • Request (application/json)

      {
            "user_code": "2D85HS31S1",
            "callback_url": "https://www.callback.co/callback",
            "event": {
               "event_type": "BALANCE_CHANGE",
               "account_type": "primary",
               "balance": { "units": "100000000", "currency": "btc" },
               "last_transaction": {
                  "transaction_type": "place_bid",
                  "created_at": "2016-01-07T18:04:45.570Z",
                  "amount": { "units": "1000000", "currency": "btc" }
               }
            }
        }

Webhooks

GET https://www.bitbond.com/api/v1/webhooks
Responses200
Headers
Content-Type: application/json
Body
{
  "webhooks": [
    {
      "id": "1",
      "callback_url": "https://www.biddingbot.com/bitbond/events?secret=xyz"
    }
  ]
}

List all webhooks
GET/webhooks


POST https://www.bitbond.com/api/v1/webhooks
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "callback_url": "https://www.biddingbot.com/bitbond/events?secret=xyz"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "callback_url": {
      "type": "string",
      "description": "A callback url to which the events will be POST'ed as json.\n"
    }
  },
  "required": [
    "callback_url"
  ]
}
Responses200422
Headers
Content-Type: application/json
Body
{}
Headers
Content-Type: application/json
Body
{
  "errors": {
    "callback_url": [
      "can't be blank",
      "must be a valid url"
    ]
  }
}

Add a new webhook
POST/webhooks

Please use only port 80 or 443.


Removing a webhook

DELETE https://www.bitbond.com/api/v1/webhooks/100123
Responses200404
Headers
Content-Type: application/json
Body
{}
Headers
Content-Type: application/json
Body
{
    message: "The resource you ware looking for was not found"
}

To delete a webhook
DELETE/webhooks/{id}

URI Parameters
HideShow
id
string (required) Example: 100123

The webhook ID


Generated by aglio on 21 Oct 2016