NAV
cURL

Introduction

Welcome to the Bitreserve API, we’re glad to have you! Provided here is all the documentation you need to help you create custom and revolutionary new services powered by the Bitreserve Platform. With your ingenuity, together we can serve the needs of individuals and organizations across the globe and change the financial services ecosystem forever.

Client Libraries

The follow libraries are available:

We are actively looking for developers to contribute Bitreserve client libraries for a variety of platforms and languages. If you have written a library, please share a link to the github repository with us at support@bitreserve.org so that we can promote it here, and collaborate with you on its further development.

API Changes

You can be notified of the latest changes by watching our official documentation repository on GitHub.

We are currently in v0 which means that breaking changes may be introduced. If there are any upcoming changes we will add them to a release named next. You can follow it in the releases page to avoid breaking your application.

The official changelog is currently on GitHub.

Authentication

Bitreserve is an OAuth 2.0 compliant service.

To use the Bitreserve API, one must present a Personal Access Token (PAT) with each request. This token establishes who you are, and what permissions you have when interacting with the API. There are two types of access tokens: a persistent token that never expires, and temporary tokens that expire after 15 minutes of inactivity. Persistent tokens are ideal for use within an application that is permanently associated with the same Bitreserve account, and for which the collection of a username and password from an end-user is not feasible. Temporary tokens can be generated and bound to any valid Bitreserve account and grants the holder of that token to act on a User’s behalf.

If you have OTP (One Time Password, also known as Two-Factor Authentication) enabled, then you will get an HTTP 401 (Unauthorized) response, along with the HTTP header X-Bitreserve-OTP: Required. You will then automatically receive an SMS, or Push Notification with your verification code, depending on whether you have the Authy app installed or not. Then execute the command above again, this time passing your OTP verification code as a header, like so: X-Bitreserve-OTP: <OTP-Token>.

OAuth 2.0

We are currently working on providing the Web Application Flow and Non-Web Application Flow. Meanwhile you can use our API using Basic Authentication or create a Personal Access Token.

Basic Authentication

Via Username/Email and Password

You can use Basic Authentication using your username or email and password combination. If you have OTP enabled you must send the X-Bitreserve-OTP in every request.

Simple request using username or email and password:

curl https://api.bitreserve.org/v0/me \
  -H 'X-Bitreserve-OTP: <OTP-Token>' \
  -u <username-or-email>:<password>

Via Personal Access Tokens

We recommend people secure Personal Access Tokens like you would a password. They are functionally equivalent, but have the advantage of being able to to be issued and revoked individually. This means if one of them gets compromised you can revoke it without affecting all the applications or clients within your ecosystem.

To create a Personal Access Token, execute the following command:

curl https://api.bitreserve.org/v0/me/tokens \
  -X POST \
  -H 'X-Bitreserve-OTP: <OTP-Token>' \
  -H "Content-Type: application/json" \
  -u <username-or-email>:<password> \
  -d '{ "description": "My command line script" }'

If your request for a token checks out, then our API will return the following:

{
  "access_token": "41ee8b1fa14042e031fe304bb4793b54e6576d19b306dc205136172b80d59d20",
  "description": "My command line script",
  "expires": null
}

Here is an example for using the personal access token to make requests to our API:

curl https://api.bitreserve.org/v0/me \
  -u 41ee8b1fa14042e031fe304bb4793b54e6576d19b306dc205136172b80d59d20:X-OAuth-Basic

Currencies

In Bitreserve’s API, we frequently call for a currency as an input or output. We represent all such currencies and stores of value by a three letter code. Listed below are the currencies and stores of value that we currently support.

Tickers

Developers can query at any time the rates we utilize when exchanging one form of value for another. These are expressed in “currency pairs.”

Get All Tickers

curl "https://api.bitreserve.org/v0/ticker"

The above command returns the following JSON:

[
  {
    "ask": "1",
    "bid": "1",
    "currency": "BTC",
    "pair": "BTCBTC"
  },
  {
    "ask": "440.99",
    "bid": "440",
    "currency": "USD",
    "pair": "BTCUSD"
  },
  {
    "ask": "1",
    "bid": "1",
    "currency": "CNY",
    "pair": "CNYCNY"
  },
  {
    "ask": "7.6865",
    "bid": "7.6731",
    "currency": "CNY",
    "pair": "EURCNY"
  },
  {
    "ask": "1",
    "bid": "1",
    "currency": "EUR",
    "pair": "EUREUR"
  },
  {
    "ask": "0.799",
    "bid": "0.7988",
    "currency": "GBP",
    "pair": "EURGBP"
  },
  {
    "ask": "145.6111",
    "bid": "145.5311",
    "currency": "JPY",
    "pair": "EURJPY"
  },
  {
    "ask": "1.253",
    "bid": "1.2528",
    "currency": "USD",
    "pair": "EURUSD"
  },
  {
    "ask": "9.6217",
    "bid": "9.6048",
    "currency": "CNY",
    "pair": "GBPCNY"
  },
  {
    "ask": "1",
    "bid": "1",
    "currency": "GBP",
    "pair": "GBPGBP"
  },
  {
    "ask": "182.2707",
    "bid": "182.1691",
    "currency": "JPY",
    "pair": "GBPJPY"
  },
  {
    "ask": "1.5685",
    "bid": "1.5683",
    "currency": "USD",
    "pair": "GBPUSD"
  },
  {
    "ask": "0.0528",
    "bid": "0.0527",
    "currency": "CNY",
    "pair": "JPYCNY"
  },
  {
    "ask": "1",
    "bid": "1",
    "currency": "JPY",
    "pair": "JPYJPY"
  },
  {
    "ask": "6.1345",
    "bid": "6.1245",
    "currency": "CNY",
    "pair": "USDCNY"
  },
  {
    "ask": "116.21",
    "bid": "116.16",
    "currency": "JPY",
    "pair": "USDJPY"
  },
  {
    "ask": "1",
    "bid": "1",
    "currency": "USD",
    "pair": "USDUSD"
  }
]

Request

GET https://api.bitreserve.org/v0/ticker

Response

Returns an associative array containing the current rates Bitreserve has on record for all currency pairs.

Get Tickers for Currency

curl "https://api.bitreserve.org/v0/ticker/USD"

The above command returns the following JSON:

[
  {
    "ask": "440.99",
    "bid": "440",
    "currency": "USD",
    "pair": "BTCUSD"
  },
  {
    "ask": "1.253",
    "bid": "1.2528",
    "currency": "USD",
    "pair": "EURUSD"
  },
  {
    "ask": "1.5685",
    "bid": "1.5683",
    "currency": "USD",
    "pair": "GBPUSD"
  },
  {
    "ask": "6.1345",
    "bid": "6.1245",
    "currency": "CNY",
    "pair": "USDCNY"
  },
  {
    "ask": "116.21",
    "bid": "116.16",
    "currency": "JPY",
    "pair": "USDJPY"
  },
  {
    "ask": "1",
    "bid": "1",
    "currency": "USD",
    "pair": "USDUSD"
  }
]

This method allows developers to find all exchanges rates relative to a given currency.

Request

GET https://api.bitreserve.org/v0/ticker/:currency

Response

Returns an associative array containing the current rates Bitreserve has on record for the currency specified.

Entities

Card Object

An example currency pair encoded in JSON looks like this:

{
  "id": "91380a1f-c6f1-4d81-a204-8b40538c1f0d",
  "address": {
    "bitcoin": "1KHpy2xrscep4RiXPiM3jyjee82iBMyMan"
  },
  "label": "BTC Card #2",
  "currency": "BTC",
  "balance": "0.00",
  "available": "0.00",
  "lastTransactionAt": "2014-07-07T05:40:46.624Z",
  "addresses": [
    {
      "id": "1KHpy2xrscep4RiXPiM3jyjee82iBMyMan",
      "network": "bitcoin"
    },
    {
      "id": "18yFebPW8USkoBtYXeV6quwgnPGEVyvpKi",
      "network": "bitcoin"
    }
  ],
  "settings": [
    {
      "position": "7",
      "starred": true
    }
  ]
}
Property Description
id A unique ID associated with the card.
address A key/value pair representing the primary address for the card.
addresses An associative array of all the known addresses associated with the card, including the primary card.
label The display name of the card as chosen by the user.
currency The currency by which the card is denominated.
balance The total balance of the card, including all pending transactions.
available The balance available for withdrawal/usage.
lastTransactionAt A timestamp of the last time a transaction on this card was conducted.
settings Contains the card’s current position and whether the card is starred or not.

Contact Object

An example contact encoded in JSON looks like this:

{
  "id": "9fae84eb-712d-4b6a-9b2c-764bdde4c079",
  "firstName": "Han",
  "lastName": "Solo",
  "company": "Independent",
  "emails": [
    "han.solo@rebelalliance.org"
  ],
  "addresses": [],
  "name": "Han Solo"
}
Property Description
id A unique ID in the Bitreserve network identifying the contact.
firstName The first name of this contact provided by the user.
lastName The last name of this contact provided by the user.
company The company of this contact provided by the user.
emails An array of known email addresses associated with this contact.
address An array of known addresses associated with this contact.
name The display name of the contact created by joining the first and last names.

Currency Pair Object

An example currency pair encoded in JSON looks like this:

"BTCUSD": {
  "bid": "599.23",
  "ask": "600.99"
}

A currency pair is the combination of two currencies, encoded as two currency codes, e.g. USD, GBP, EUR, concatenated together to represent the current status of converting the first currency into the second. For example, the currency pair “BTCUSD” represents moving from bitcoin to US dollars.

Each currency pair has three properties:

Property Description
bid The current bid price, or the price we quote when buying the asset.
ask The current ask price, or the price we quote when selling the asset.

User Object

An example user encoded in JSON looks like this:

{
  "username": "byrnereese",
  "email": "byrne@bitreserve.org",
  "firstName": "Byrne",
  "lastName": "Reese",
  "name": "Byrne Reese",
  "country": "US",
  "state": "CA",
  "currencies": [
    "BTC",
    "USD",
    "EUR",
    "GBP",
    "CNY",
    "JPY",
    "XAU"
  ],
  "status": {
    "email": "ok",
    "phone": "pending",
    "review": "pending",
    "volume": "ok",
    "identity": "pending",
    "overview": "pending",
    "screening": "pending",
    "registration": "running"
  },
  "settings": {
    "theme": "minimalistic",
    "currency": "USD",
    "hasNewsSubscription": "true",
    "intl": {
      "language": {
        "locale": "en-US"
      },
      "dateTimeFormat": {
        "locale": "en-US"
      },
      "numberFormat": {
        "locale": "en-US"
      }
    },
    "hasOtpEnabled": "false"
  },
  "phones":[
    {
      "id": "1d78aeb5-43ac-4ee8-8d28-1291b5d8355c",
      "verified": "true",
      "primary": "true",
      "e164Masked": "+XXXXXXXXX04",
      "nationalMasked": "(XXX) XXX-XX04",
      "internationalMasked": "+X XXX-XXX-XX04"
    }
  ],
  "balances": {
    "total": "1083.77",
    "currencies": {
      "CNY": {
        "amount": "6.98",
        "balance": "42.82",
        "currency": "USD",
        "rate": "6.13880"
      },
      "EUR": {
        "amount": "75.01",
        "balance": "58.05",
        "currency": "USD",
        "rate": "1.29220"
      }
    }
  },
  "cards": <snip>,
  "transactions": <snip>
}

The user object contains all information we have on record relating to the currently logged in user.

User Status

We communicate a number of different user states through our API. At a high-level accounts can be in one of four states:

When members are in restricted or blocked state, the flags field can help communicate the reasons for account suspension. These flags, and their permissible values are:

Flag Permissible Values Description
email pending, ok The status of email verification.
registration pending, running, ok Where a user is in the registration process.
phone pending, running, ok The status of phone number verification.
ofac pending, ready, running, ok, failed The status of whether a user has cleared OFAC screening.
identity pending, ready, running, ok, failed The status of identity verification during membership application process.
verification pending, ready, ok, failed The status of user data verification.

Transaction Object

An example transaction encoded in JSON looks like this:

{
  "id": "a97bb994-6e24-4a89-b653-e0a6d0bcf634",
  "message": "",
  "type": "invite",
  "status": "waiting",
  "RefundedById": null,
  "createdAt": "2014-08-27T00:01:11.616Z",
  "denomination": {
    "rate": "1.00",
    "amount": "1.00",
    "currency": "USD"
  },
  "origin": {
    "address": "1GpBtJXXa1NdG94cYPGZTc3DfRY2P7EwzH",
    "base": "1.00",
    "commission": "0.00",
    "fee": "0.00",
    "amount": "1.00",
    "CardId": "ade869d8-7913-4f67-bb4d-72719f0a2be0",
    "currency": "USD",
    "description": "Luke Skywalker",
    "rate": "1.00",
    "sources": [
      {
        "id": "35325c99-edeb-4625-9cd8-f56d4783c352",
        "amount": "1"
      }
    ],
    "type": "card"
  },
  "destination": {
    "address": "1PtbHc2C3DHQmTRMxMd1DJgH7AKubjhbip",
    "base": "1.00",
    "commission": "0.00",
    "fee": "0.00",
    "amount": "1.00",
    "CardId": "e3bc8674-f647-42f1-91b5-0395458ee81c",
    "currency": "USD",
    "description": "leia.organa@senate.coruscant.gov",
    "rate": "1.00",
    "type": "email"
  },
  "params": {
    "pair": "USDUSD",
    "margin": "0.00",
    "currency": "USD",
    "rate": "1.00",
    "progress": "0",
    "ttl": 30000
  }
}

Transactions record the movement of value into, within and out of the Bitreserve network. Transactions have the following properties:

Property Description
id A unique ID on the Bitreserve Network associated with the transaction.
message A message or note provided by the user at the time the transaction was initiated, with the intent of communicating additional information and context about the nature/purpose of the transaction.
status The current status of the transaction. Possible values are: pending, waiting, cancelled or completed.
type The nature of the transaction. Possible values are invite, transfer, external/out, internal, and external/in.
RefundedById When a transaction is cancelled, specifically a transaction in which money is sent to an email address, this contains the transaction ID of the transaction which refunds the amount back to the user.
createdAt The date and time the transaction was initiated.
denomination The funds to be transfered, as originally requested. See “Denomination” below.
origin The sender of the funds. See “Origin and Destination” below.
destination The recipient of the funds. See “Origin and Destination” below.
params Other parameters of this transaction.

Denomination

The actual value being transacted is denominated in a certain currency, as expressed by the denomination field with the following properties:

Property Description
amount The amount to be transacted.
currency The currency for said amount.
rate The quoted rate for converting between the denominated currency and the currency at origin.

Origin

The origin has properties regarding how the transaction affects the account at origin of the funds:

Property Description
address The address from which funds were taken.
base The amount to debit the origin account, before commissions or fees.
commission The commission charged by Bitreserve to process the transaction.
fee The Bitcoin network Fee, if origin is in BTC but destination is not, or is a non-Bitreserve Bitcoin Address.
amount The amount debited to the origin account, including commissions and fees.
CardId The ID of the card debited. Only visible to the user who sends the transaction.
currency The currency of the funds at the origin acount.
description The name of the sender.
rate The rate for conversion between origin and destination, as expressed in the currency at origin (the inverse of destination.rate).
type The type of endpoint. Possible values are ‘card’ and ‘external’

Destination

The destination of a transaction has its own set of properties describing how the destination account is affected, which include:

Property Description
address The address to which funds were directed.
base The amount to credit the destination account, before commissions or fees.
commission The commission charged by Bitreserve to process the transaction. Commissions are only charged when currency is converted into a different denomination.
fee The Bitcoin network Fee, if destination is a BTC account but origin is not.
amount The amount credited to the destination account, including commissions and fees.
CardId The ID of the card credited. Only visible to the user who receives the transaction.
currency The denomination of the funds at the time they were sent/received.
description The name of the recipient. In the case where money is sent via email, the description will contain the email address of the recipient.
rate The rate for conversion between origin and destination, as expressed in the currency at destination (the inverse of origin.rate).
type The type of endpoint. Possible values are ‘email’, ‘card’ and ‘external’.

Parameters

The params property associated with a transaction records additional meta data relating to the respective transaction. It contains the following properties:

Property Description
pair The currency pair associated with any exchange that took place, if any.
margin Bitreserve’s commission expressed in percentage.
commission The total commission taken on this transaction, either at origin or at destination.
currency The currency in which the total commission is expressed.
rate The exchange rate for this pair.
progress In case a transaction is coming in from the outside, how many confirmations have been received.
ttl The time this quote is good for, in milliseconds ([0-30000]).

Cards

Bitreserve uses the concept of a “card” as a store of value. Each card is denominated by a currency or store of value, and every card is automatically provisioned one or more addresses to which value can be sent. Whenever value flows into a card, Bitreserve automatically converts that value into the value determined by the card’s denomination. In the world of bitcoin for example, this allows one to preserve the original value sent by the sender and shields the recipient from any volatility they might be exposed to by holding bitcoin directly. This also allows recipients of funds to normalize all incoming funds to a single store of value regardless of how the value was originally sent.

List Cards

curl "https://api.bitreserve.org/v0/me/cards"
  -H "Authorization: Bearer <token>"

The above command returns the following JSON:

[
  {
    "id": "ade869d8-7913-4f67-bb4d-72719f0a2be0",
    "address": {
      "bitcoin": "1GpBtJXXa1NdG94cYPGZTc3DfRY2P7EwzH"
    },
    "label": "USD card",
    "currency": "USD",
    "balance": "897.29",
    "available": "897.29",
    "lastTransactionAt": "2014-09-24T18:11:53.561Z",
    "addresses": [
      {
        "id": "1GpBtJXXa1NdG94cYPGZTc3DfRY2P7EwzH",
        "network": "bitcoin"
      }
    ],
    "settings": [
      {
        "position": "1",
        "starred": true
      }
    ]
  },
  {
    "id": "91380a1f-c6f1-4d81-a204-8b40538c1f0d",
    "address": {
      "bitcoin": "1KHpy2xrscep4RiXPiM3jyjee82iBMyMan"
    },
    "label": "BTC Card #2",
    "currency": "BTC",
    "balance": "0.00",
    "available": "0.00",
    "lastTransactionAt": "2014-07-07T05:40:46.624Z",
    "addresses": [
      {
        "id": "1KHpy2xrscep4RiXPiM3jyjee82iBMyMan",
        "network": "bitcoin"
      },
      {
        "id": "18yFebPW8USkoBtYXeV6quwgnPGEVyvpKi",
        "network": "bitcoin"
      }
    ],
    "settings": [
      {
        "position": "7",
        "starred": true
      }
    ]
  }
]

Retrieves a list of cards for the current user.

Request

GET https://api.bitreserve.org/v0/me/cards

Response

Returns an array of the current user’s cards.

Get Card Details

curl "https://api.bitreserve.org/v0/me/cards/37e002a7-8508-4268-a18c-7335a6ddf24b"
  -H "Authorization: Bearer <token>"

The above command returns the following JSON:

{
  "id": "2b2eb351-b1cc-48f7-a3d0-cb4f1721f3a3",
  "address": {
    "bitcoin": "145ZeN94MAtTmEgvhXEch3rRgrs7BdD2cY"
  },
  "label": "CNY card",
  "currency": "CNY",
  "balance": "42.82",
  "available": "42.82",
  "lastTransactionAt": "2014-06-16T20:46:51.002Z",
  "addresses": [
    {
      "id": "145ZeN94MAtTmEgvhXEch3rRgrs7BdD2cY",
      "network": "bitcoin"
    }
  ],
  "settings": [
    {
      "position": "5",
      "starred": true
    }
  ]
}

Retrieves the details about a specific card.

Request

GET https://api.bitreserve.org/v0/me/cards/:id

Response

Returns the details associated with the card ID provided.

Create Card

curl -X POST --data "label=My+New+Card&currency=USD" \
  -H "Authorization: Bearer <token>" \
  https://api.bitreserve.org/v0/me/cards

Request

POST https://api.bitreserve.org/v0/me/cards

Parameter Default Description
label The display name of the card. Max length: 140 characters.
currency The currency to denominate value stored by the card, represented as a three character currency code.

Response

Returns a fully formed Card Object representing the card created.

Transactions

Create & Commit a Transaction

Step 1: Create the Transaction

curl "https://api.bitreserve.org/v0/me/cards/a6d35fcd-xxxx-9c9d1dda6d57/transactions" \
  -X POST \
  -H "Authorization: Bearer <token>" \
  -d "denomination[currency]=BTC&denomination[amount]=0.1&destination=foo@bar.com"

The above command returns the following JSON:

{
  "id": "7c377eba-cb1e-45a2-8c13-9807b4139bec",
  "type": "transfer",
  "message": null,
  "status": "pending",
  "RefundedById":null,
  "createdAt": "2014-08-27T00:01:11.616Z",
  "denomination": {
    "amount": "0.1",
    "currency": "BTC",
    "pair": "BTCBTC",
    "rate": "1.00"
  },
  "origin": {
    "CardId": "66cf2c86-8247-4094-bbec-ca29cea8220f",
    "amount": "0.1",
    "base": "0.1",
    "commission": "0.00",
    "currency": "BTC",
    "description": "John Doe",
    "fee": "0.00",
    "rate": "1.00",
    "type": "card",
    "username": "johndoe"
  },
  "destination": {
    "amount": "0.1",
    "base": "0.1",
    "commission": "0.00",
    "currency": "BTC",
    "description": "foo@bar.com",
    "fee": "0.00",
    "rate": "1.00",
    "type": "email"
  },
  "params": {
    "currency": "BTC",
    "margin": "0.00",
    "pair": "BTCBTC",
    "rate": "1.00",
    "ttl": 30000,
    "type": "invite"
  }
}

Step 2: Commit the Transaction

curl "https://api.bitreserve.org/v0/me/cards/a6d35fcd-xxxx-9c9d1dda6d57/transactions/d51b4e4e-9827-40fb-8763-e0ea2880085b/commit" \
  -X POST \
  -H "Authorization: Bearer <token>"

Returns a Transaction Object.

Step 1: Create Transaction

In step one, one prepares the transaction by specifying:

Upon preparing a transaction, a Transaction Object will be returned with a newly-generated id.

Request

POST https://api.bitreserve.org/v0/me/cards/:card/transactions

Response

Returns a Transaction Object.

Step 2: Commit Transaction

Once a transaction has been created and a quote secured, commit the transaction using the previously returned id. An optional parameter message can also be sent which will overwrite the value currently stored in the transaction.

Request

POST https://api.bitreserve.org/v0/me/cards/:card/transactions/:id/commit

Response

Returns a Transaction Object.

Cancel a Transaction

curl "https://api.bitreserve.org/v0/me/cards/a6d35fcd-xxxx-9c9d1dda6d57/transactions/d51b4e4e-9827-40fb-8763-e0ea2880085b/cancel" \
  -X POST \
  -H "Authorization: Bearer <token>"

Returns a Transaction Object.

Cancels a transaction that has not yet been redeemed.

Request

POST https://api.bitreserve.org/v0/me/cards/:card/transactions/:id/cancel

Response

Returns a Transaction Object.

Resend a Transaction

curl "https://api.bitreserve.org/v0/me/cards/a6d35fcd-xxxx-9c9d1dda6d57/transactions/d51b4e4e-9827-40fb-8763-e0ea2880085b/resend" \
  -X POST \
  -H "Authorization: Bearer <token>"

Returns a Transaction Object.

Triggers a reminder for a transaction that hasn’t been redeemed yet.

Request

POST https://api.bitreserve.org/v0/me/cards/:card/transactions/:id/resend

Response

Returns a Transaction Object.

List User Transactions

curl "https://api.bitreserve.org/v0/me/transactions" \
  -X GET \
  -H "Authorization: Bearer <token>"

The above command returns the following JSON:

[
  {
    "id": "a97bb994-6e24-4a89-b653-e0a6d0bcf634",
    "type": "transfer",
    "message": null,
    "status": "waiting",
    "RefundedById":null,
    "createdAt": "2014-08-27T00:01:11.616Z",
    "denomination": {
      "rate": "1.00",
      "amount": "1.00",
      "currency": "USD"
    },
    "origin": "<excluded for brevity>",
    "destination": "<excluded for brevity>",
    "params": "<excluded for brevity>"
  },
  {
    "id": "b97bb994-6e24-4a89-b653-e0a6d0bcf635",
    "type": "transfer",
    "message": null,
    "status": "waiting",
    "RefundedById":null,
    "createdAt": "2014-08-27T00:01:12.616Z",
    "denomination": {
      "rate": "1.00",
      "amount": "1.00",
      "currency": "USD"
    },
    "origin": "<excluded for brevity>",
    "destination": "<excluded for brevity>",
    "params": "<excluded for brevity>"
  }
]

Requests a list of transactions associated with the current user.

Request

GET https://api.bitreserve.org/v0/me/transactions

This endpoint supports Pagination.

Response

Returns an array of Transaction Objects.

List Card Transactions

curl "https://api.bitreserve.org/v0/me/cards/2b2eb351-b1cc-48f7-a3d0-cb4f1721f3a3/transactions" \
  -X GET \
  -H "Authorization: Bearer <token>"

The above command returns the following JSON:

[
  {
    "id": "a97bb994-6e24-4a89-b653-e0a6d0bcf634",
    "type": "transfer",
    "message": null,
    "status": "waiting",
    "RefundedById":null,
    "createdAt": "2014-08-27T00:01:11.616Z",
    "denomination": {
      "rate": "1.00",
      "amount": "1.00",
      "currency": "USD"
    },
    "origin": "<excluded for brevity>",
    "destination": "<excluded for brevity>",
    "params": "<excluded for brevity>"
  },
  {
    "id": "b97bb994-6e24-4a89-b653-e0a6d0bcf635",
    "type": "transfer",
    "message": null,
    "status": "waiting",
    "RefundedById":null,
    "createdAt": "2014-08-27T00:01:12.616Z",
    "denomination": {
      "rate": "1.00",
      "amount": "1.00",
      "currency": "USD"
    },
    "origin": "<excluded for brevity>",
    "destination": "<excluded for brevity>",
    "params": "<excluded for brevity>"
  }
]

Requests a list of transactions associated with a specific card.

Request

GET https://api.bitreserve.org/v0/me/cards/:card/transactions

This endpoint supports Pagination.

Response

Returns an array of Transaction Objects.

Get All Transactions (Public)

curl -X GET "https://api.bitreserve.org/v0/reserve/transactions"

The above command returns the following JSON, truncated for brevity:

[
  {
    "id": "63dc7ccb-0e57-400d-8ea7-7d903753801c",
    "type": "deposit",
    "params": {
      "margin": "0.45",
      "pair": "BTCUSD",
      "type": "transfer"
    },
    "denomination": {
      "amount": "25.00",
      "currency": "USD"
    },
    "origin": {
      "amount": "25.00",
      "base": "25.00",
      "commission": "0.00",
      "currency": "USD",
      "fee": "0.00",
      "rate": "408.19000"
    },
    "destination": {
      "amount": "0.06087161",
      "base": "0.06124598",
      "commission": "0.00027437",
      "currency": "BTC",
      "fee": "0.0001",
      "rate": "0.00244983"
    },
    "status": "completed",
    "createdAt": "2014-09-25T19:19:51.201Z"
  },
  {
    "id": "fc4263a8-5df0-493d-bd26-517a218c7089",
    "type": "deposit",
    "params": {
      "margin": "0.00",
      "pair": "BTCBTC",
      "type": "external/out"
    },
    "denomination": {
      "amount": "0.45",
      "currency": "BTC"
    },
    "origin": {
      "amount": "0.4501",
      "base": "0.45",
      "commission": "0.00",
      "currency": "BTC",
      "fee": "0.0001",
      "rate": "1.00"
    },
    "destination": {
      "amount": "0.45",
      "base": "0.45",
      "commission": "0.00",
      "currency": "BTC",
      "fee": "0.00",
      "rate": "1.00"
    },
    "status": "completed",
    "createdAt": "2014-09-25T18:11:50.182Z"
  }
]

See also: Transparency: Reservechain

Requests the public view of all transactions in the reserve.

Request

GET https://api.bitreserve.org/v0/reserve/transactions

This endpoint supports Pagination.

Response

Returns an array of Transaction Objects.

Get Transaction (Public)

curl -X GET "https://api.bitreserve.org/v0/reserve/transactions/a97bb994-6e24-4a89-b653-e0a6d0bcf634"

The above command returns the following JSON:

{
  "id": "a97bb994-6e24-4a89-b653-e0a6d0bcf634",
  "type": "deposit",
  "params": {
    "type": "invite",
    "pair": "USDUSD"
  },
  "denomination": {
    "amount": "1.00",
    "currency": "USD"
  },
  "origin": {
    "base": "1.00",
    "amount": "1.00",
    "commission": "0.00",
    "fee": "0.00",
    "currency": "USD"
  },
  "destination": {
    "base": "1.00",
    "amount": "1.00",
    "commission": "0.00",
    "fee": "0.00",
    "currency": "USD"
  },
  "status": "waiting",
  "createdAt": "2014-09-25T18:11:50.182Z"
}

See also: Transparency: Reservechain

Requests the public view of a specific transaction.

Request

GET https://api.bitreserve.org/v0/reserve/transactions/:id

Response

Returns a Transaction Object.

Contacts

List Contacts

curl "https://api.bitreserve.org/v0/me/contacts" \
  -H "Authorization: Bearer <token>"

The above command returns the following JSON:

[
  {
    "id": "9fae84eb-712d-4b6a-9b2c-764bdde4c079",
    "firstName": "Han",
    "lastName": "Solo",
    "company": "Rebel Alliance",
    "emails": [
      "han.solo@rebelalliance.org"
    ],
    "addresses": [],
    "name": "Han Solo"
  },
  {
    "id": "2f3b26bf-4621-4fe9-ab7d-565105b22588",
    "firstName": "Leia",
    "lastName": "Organa",
    "company": "Galactic Senate",
    "emails": [
      "leia.organa@senate.coruscant.gov"
    ],
    "addresses": [],
    "name": "Leia Organa"
  }
]

Request

GET https://api.bitreserve.org/v0/me/contacts

Response

Returns an array of contact objects associated with the current user.

Get Contact

curl "https://api.bitreserve.org/v0/me/contacts/9fae84eb-712d-4b6a-9b2c-764bdde4c079" \
  -H "Authorization: Bearer <token>"

The above command returns the following JSON:

{
  "id": "9fae84eb-712d-4b6a-9b2c-764bdde4c079",
  "firstName": "Han",
  "lastName": "Solo",
  "company": "Rebel Alliance",
  "emails": [
    "han.solo@rebelalliance.org"
  ],
  "addresses": [],
  "name": "Han Solo"
}

Request

GET https://api.bitreserve.org/v0/me/contacts/:id

Response

Returns an associative array containing the details of the designated contact.

Create Contact

curl -X POST --data "firstName=Luke&lastName=Skywalker&company=Lars+Moisture+Farm,+Inc.&emails=support@larsmoisturefarm.com" \
  -H "Authorization: Bearer <token>" \
  https://api.bitreserve.org/v0/me/contacts

Request

POST https://api.bitreserve.org/v0/me/contacts

Parameter Default Description
firstName Contact’s first name. (max: 255 chars)
lastName Contact’s last name. (max: 255 chars)
company Contact’s company. (max: 255 chars)
emails List of email addresses.
addresses List of bitcoin addresses.

Response

A fully formed Contact Object

Users

Get User

curl "https://api.bitreserve.org/v0/me"
  -H "Authorization: Bearer <token>"

The above command returns the following JSON:

{
  "username": "byrnereese",
  "email": "byrne@bitreserve.org",
  "firstName": "Byrne",
  "lastName": "Reese",
  "name": "Byrne Reese",
  "country": "US",
  "state": "CA",
  "currencies": [
    "BTC",
    "USD",
    "EUR",
    "GBP",
    "CNY",
    "JPY",
    "XAU"
  ],
  "status": {
    "email": "ok",
    "phone": "pending",
    "review": "pending",
    "volume": "ok",
    "identity": "pending",
    "overview": "pending",
    "screening": "pending",
    "registration": "running"
  },
  "settings": {
    "theme": "minimalistic",
    "currency": "USD",
    "hasNewsSubscription": "true",
    "intl": {
      "language": {
        "locale": "en-US"
      },
      "dateTimeFormat": {
        "locale": "en-US"
      },
      "numberFormat": {
        "locale": "en-US"
      }
    },
    "hasOtpEnabled": "false"
  },
  "phones": [
    {
      "id": "1d78aeb5-43ac-4ee8-8d28-1291b5d8355c",
      "verified": "true",
      "primary": "true",
      "e164Masked": "+XXXXXXXXX04",
      "nationalMasked": "(XXX) XXX-XX04",
      "internationalMasked": "+X XXX-XXX-XX04"
    }
  ],
  "balances": {
    "total": "1083.77",
    "currencies": {
      "CNY": {
        "amount": "6.98",
        "balance": "42.82",
        "currency": "USD",
        "rate": "6.13880"
      },
      "EUR": {
        "amount": "75.01",
        "balance": "58.05",
        "currency": "USD",
        "rate": "1.29220"
      }
    }
  },
  "cards": [
    {
      "id": "2b2eb351-b1cc-48f7-a3d0-cb4f1721f3a3",
      "address": {
        "bitcoin": "145ZeN94MAtTmEgvhXEch3rRgrs7BdD2cY"
      },
      "label": "CNY card",
      "currency": "CNY",
      "balance": "42.82",
      "available": "42.82",
      "lastTransactionAt": "2014-06-16T20:46:51.002Z",
      "addresses": [
        {
          "id": "145ZeN94MAtTmEgvhXEch3rRgrs7BdD2cY",
          "network": "bitcoin"
        }
      ],
      "settings": [
        {
          "position": "5",
          "starred": true
        }
      ]
    }
  ]
}

Request

GET https://api.bitreserve.org/v0/me

Response

Returns the details associated the current user.

Get User Phone Numbers

curl "https://api.bitreserve.org/v0/me/phones"
  -H "Authorization: Bearer <token>"

The above command returns the following JSON:

[
  {
    "id": "1d78aeb5-43ac-4ee8-8d28-1291b5d8355c",
    "verified": "true",
    "primary": "true",
    "e164Masked": "+XXXXXXXXX04",
    "nationalMasked": "(XXX) XXX-XX04",
    "internationalMasked": "+X XXX-XXX-XX04"
  }
]

Request

GET https://api.bitreserve.org/v0/me/phones

Response

Returns an array of all the phone numbers associated with the current user.

Transparency

The following section outlines a system for how Bitreserve will provide the transparency our members require in order to ascertain the solvency of the reserve we operate to protect the value entrusted to us by our Members.

We will provide our members with access to two different resources. The first is the Bitreserve Ledger, or “Reserveledger” as we call it. The Reserveledger is a real-time listing of all the company’s assets and liabilities. Each entry in the ledger can reference one or more transactions that a user can inquire about and obtain the details of via the second key resource: the Reservechain.

Reserve Status

curl "https://api.bitreserve.org/v0/reserve/statistics"

Which returns the following:

[
  {
    "currency": "BTC",
    "values": [
      {
        "assets": "287.24725",
        "currency": "BTC",
        "liabilities": "133.789096",
        "rate": "1.00"
      },
      {
        "assets": "592404.25",
        "currency": "CNY",
        "liabilities": "275919.87",
        "rate": "2062.34967"
      },
      {
        "assets": "76787.16",
        "currency": "EUR",
        "liabilities": "35764.61",
        "rate": "267.31889"
      },
      {
        "assets": "60512.35",
        "currency": "GBP",
        "liabilities": "28184.40",
        "rate": "210.66168"
      },
      {
        "assets": "10591340.78",
        "currency": "JPY",
        "liabilities": "4933052.69",
        "rate": "36871.86292"
      },
      {
        "assets": "96843.97",
        "currency": "USD",
        "liabilities": "45106.32",
        "rate": "337.14500"
      }
    ],
    "totals": {
      "commissions": "7.47763",
      "transactions": "1755.86701",
      "assets": "493.75857302",
      "liabilities": "335.82190088"
    }
  },
  {
    "currency": "CNY",
    "values": [
      {
        "assets": "0.00",
        "currency": "BTC",
        "liabilities": "1.02929007",
        "rate": "0.00048486"
      },
      {
        "assets": "0.00",
        "currency": "CNY",
        "liabilities": "2122.73",
        "rate": "1.00"
      },
      {
        "assets": "0.00",
        "currency": "EUR",
        "liabilities": "275.15",
        "rate": "0.12962"
      },
      {
        "assets": "0.00",
        "currency": "GBP",
        "liabilities": "216.83",
        "rate": "0.10214"
      },
      {
        "assets": "0.00",
        "currency": "JPY",
        "liabilities": "37939.77",
        "rate": "17.87310"
      },
      {
        "assets": "0.00",
        "currency": "USD",
        "liabilities": "347.02",
        "rate": "0.16347"
      }
    ],
    "totals": {
      "commissions": "16282.33",
      "transactions": "3823508.63",
      "assets": "1018302.81",
      "liabilities": "692583.22"
    }
  },
  {
    "currency": "EUR",
    "values": [
      {
        "assets": "0.00",
        "currency": "BTC",
        "liabilities": "12.99977754",
        "rate": "0.00374082"
      },
      {
        "assets": "0.00",
        "currency": "CNY",
        "liabilities": "26809.95",
        "rate": "7.71485"
      },
      {
        "assets": "0.00",
        "currency": "EUR",
        "liabilities": "3475.11",
        "rate": "1.00"
      },
      {
        "assets": "0.00",
        "currency": "GBP",
        "liabilities": "2738.56",
        "rate": "0.78805"
      },
      {
        "assets": "0.00",
        "currency": "JPY",
        "liabilities": "479323.83",
        "rate": "137.93055"
      },
      {
        "assets": "0.00",
        "currency": "USD",
        "liabilities": "4382.81",
        "rate": "1.26120"
      }
    ],
    "totals": {
      "commissions": "2093.29",
      "transactions": "491498.28",
      "assets": "131991.93",
      "liabilities": "89772.20"
    }
  },
  {
    "currency": "GBP",
    "values": [
      {
        "assets": "0.00",
        "currency": "BTC",
        "liabilities": "6.66475849",
        "rate": "0.00474691"
      },
      {
        "assets": "0.00",
        "currency": "CNY",
        "liabilities": "13745.15",
        "rate": "9.78985"
      },
      {
        "assets": "0.00",
        "currency": "EUR",
        "liabilities": "1781.64",
        "rate": "1.26895"
      },
      {
        "assets": "0.00",
        "currency": "GBP",
        "liabilities": "1404.02",
        "rate": "1.00"
      },
      {
        "assets": "0.00",
        "currency": "JPY",
        "liabilities": "245743.23",
        "rate": "175.02830"
      },
      {
        "assets": "0.00",
        "currency": "USD",
        "liabilities": "2246.99",
        "rate": "1.60040"
      }
    ],
    "totals": {
      "commissions": "1648.42",
      "transactions": "387091.81",
      "assets": "104016.64",
      "liabilities": "70745.21"
    }
  },
  {
    "currency": "JPY",
    "values": [
      {
        "assets": "0.00",
        "currency": "BTC",
        "liabilities": "1.78214122",
        "rate": "0.0000271"
      },
      {
        "assets": "0.00",
        "currency": "CNY",
        "liabilities": "3676.53",
        "rate": "0.05595"
      },
      {
        "assets": "0.00",
        "currency": "EUR",
        "liabilities": "476.41",
        "rate": "0.00725"
      },
      {
        "assets": "0.00",
        "currency": "GBP",
        "liabilities": "375.43",
        "rate": "0.00571"
      },
      {
        "assets": "0.00",
        "currency": "JPY",
        "liabilities": "65710.91",
        "rate": "1.00"
      },
      {
        "assets": "0.00",
        "currency": "USD",
        "liabilities": "600.84",
        "rate": "0.00914"
      }
    ],
    "totals": {
      "commissions": "286882.91",
      "transactions": "67366825.69",
      "assets": "18205797.97",
      "liabilities": "12382365.53"
    }
  },
  {
    "currency": "USD",
    "values": [
      {
        "assets": "206.51132302",
        "currency": "BTC",
        "liabilities": "179.55683756",
        "rate": "0.00296608"
      },
      {
        "assets": "425898.56",
        "currency": "CNY",
        "liabilities": "370308.99",
        "rate": "6.11710"
      },
      {
        "assets": "55204.77",
        "currency": "EUR",
        "liabilities": "47999.28",
        "rate": "0.79289"
      },
      {
        "assets": "43504.29",
        "currency": "GBP",
        "liabilities": "37825.97",
        "rate": "0.62484"
      },
      {
        "assets": "7614457.19",
        "currency": "JPY",
        "liabilities": "6620595.10",
        "rate": "109.36500"
      },
      {
        "assets": "69624.26",
        "currency": "USD",
        "liabilities": "60536.69",
        "rate": "1.00"
      }
    ],
    "totals": {
      "commissions": "2652.43",
      "transactions": "622844.43",
      "assets": "166468.23",
      "liabilities": "113220.67"
    }
  }
]

To assist developers with tracking the overall status of our Reserve, we provide a summary of all the obligations and assets within it. Then for convenience’s sake we compute the value of each our holdings in all of the currencies we support, making it easy for example to display our total US dollar liabilities, but expressed in Euros. For example, a request to fetch a summary will return an array of assets with the following properties:

Property Description
currency The asset class of the holding being summarized.
values Expresses the value of held in the associated currency in all supported forms.
totals Lists the commissions, transaction volume, assets and liabilities.

Each normalized holding has the following properties:

Property Description
assets The quantity of assets held for the corresponding holding, but converted to a different currency.
liabilities The quantity of liabilities for the corresponding holding, but converted to a different currency.
currency The currency we are computing the current holding in.
rate The rate we used when computing the holding to the corresponding currency.

Request

GET https://api.bitreserve.org/v0/reserve/statistics

The Reserveledger

Our ledger provides a detailed record of the obligations (a.k.a. “liabilities”) flowing into our network via our members, and the resulting changes we as a company make to the assets in our reserve to secure the value of those obligations.

The ledger is made up of “entries,” each of which contains information about the change to an asset, a liability, or both, and references the related transactions that affected the change whenever possible.

Frequently one may find that changes to the Reserve’s assets and liabilities are not made in lock step with one another, and that the Reserve may accrue liabilities of one asset type or another, and then have those liabilities offset by a single change to the Reserve’s assets.

Request

curl "https://api.bitreserve.org/v0/reserve/ledger"

GET https://api.bitreserve.org/v0/reserve/ledger

This endpoint supports Pagination.

Deposits

The following entry shows how a deposit of 0.5 bitcoin by a user would be encoded on the Reserveledger. Every deposit results in two entries in the ledger. The first records the acquisition of a liability, and the second the genesis of an asset. Specifically, it shows the creation of 0.5 bitcoin as an obligation to the user, plus the acquisition of 0.5 bitcoin as an asset.

{
  "type": "liability",
  "out": {
    "amount": "0.00",
    "currency": "BTC"
  },
  "in": {
    "amount": "0.5",
    "currency": "BTC"
  },
  "TransactionId": "e205b50e-6649-416d-82c1-98f0ba44dcd9",
  "createdAt": "2014-10-08T12:26:29.844Z"
},
{
  "type": "asset",
  "out": {
    "amount": "0.00",
    "currency": "BTC"
  },
  "in": {
    "amount": "0.5",
    "currency": "BTC"
  },
  "createdAt": "2014-10-08T12:26:29.844Z"
}

Transfer of Value

The entry below shows how a user transferring 1.3 bitcoin to a “dollar card,” effectively exchanging bitcoin for dollars, would be encoded on the ledger. In this entry, two liabilities are affected. The first is a loss of 1.3 BTC as an obligation, and the second is a gain of $507.51 USD as an obligation. Which makes sense: when a user transfers the bitcoin to their dollar card, Bitreserve no longer owes them that bitcoin. Instead, Bitreserve owes them the $507.51 they exchanged for that bitcoin.

{
  "type": "liability",
  "out": {
    "amount": "1.3",
    "currency": "BTC"
  },
  "in": {
    "amount": "507.51",
    "currency": "USD"
  },
  "TransactionId": "1571fbef-d34e-447c-9b6e-4ad775953082",
  "createdAt": "2014-09-30T20:29:36.575Z"
}

This transfer of value affects our liabilities immediately and in real-time, and thus is reflected in real-time in the ledger. But when our obligations to our members change a possible imbalance in our Reserve is introduced. To compensate for this, we must make changes to the assets as well. These changes to our assets may or may not happen in real-time. This would therefore be recorded in our ledger at some point in the future as follows:

{
  "type": "asset",
  "out": {
    "amount": "1.3",
    "currency": "BTC"
  },
  "in": {
    "amount": "507.51",
    "currency": "USD"
  },
  "createdAt": "2014-09-30T20:29:36.575Z"
}

The examples above are nearly identical from one another due to the simplicity of the use case it elucidates. Consider however that when operating normally it is likely that a series of changes to our liabilities will be aggregated and accounted for in a single change to our assets in order to restore balance to the reserve.

Withdrawal of Bitcoin

When value is removed from the Reserve, two entries are added. One accounting for the change in assets, and the other for the change in liabilities. The following entry shows how a user transmitting some bitcoin to an external network/wallet would be encoded on the ledger. It shows the removal of a liability of bitcoin to the user, and the subsequent removal of bitcoin as an asset.

{
  "type": "asset",
    "out": {
    "amount": "0.10359178",
    "currency": "BTC"
  },
  "in": {
    "amount": "0.00",
    "currency": "BTC"
  },
  "createdAt": "2014-10-08T06:53:51.080Z"
},
{
  "type": "liability",
  "out": {
    "amount": "0.10359178",
    "currency": "BTC"
  },
  "in": {
    "amount": "0.00",
    "currency": "BTC"
  },
  "TransactionId": "6ab1f3e8-3b84-40b0-aec7-8008117c9f86",
  "createdAt": "2014-10-08T06:53:51.080Z"
}

Reallocation of Assets

Bitreserve may decide to secure the value of its Reserve by holding value in asset classes which may or may not correlate to how our liabilities are denominated among our members. For example, Bitreserve may wish to convert $1,000,000 in cash into a security of equal value. These changes to the Reserve do not relate to any specific transaction, but need to be accounted for nonetheless. What follows is how we could encode shifting 1M dollars into a US Treasury Bill. Take note that we can optionally include additional data relating to the asset class.

{
  "type": "asset",
  "out": {
    amount: "1000000",
    currency: "USD"
  },
  "in": {
    "amount": "1",
    "currency": "T-Bill"
    "meta": {
      "maturityDate": '2016-05-01 00:00:00 UTC',
      "principal": 1000000,
      "rate": 1.5,
      "cusip": 345370860
    }
  },
  "createdAt": "2014-10-08T06:53:51.080Z"
}

The Reservechain

Bitreserve’s Reservechain is a record of all of the transactions made by its Members that move value through the network. It is a “chain” in that any value moved in a transaction can be easily traced back to it’s origin.

At a high level, each transaction in the Reservechain contains the following key pieces of information:

Traceability

Just like a block chain, the Reservechain is both completely transparent, and traceable. For a transaction to be traceable, the value encapsulated by the transaction must reference all the places within the chain where that value is drawn from. This is done by providing a list of transaction IDs, and the value drawn from each. By following these transactions you walk backwards down different paths of the Reservechain until you ultimately find a genesis point for all value accounted for in the transaction.

Security and Privacy

All transactions are made public, but specific details about the transaction may be withheld from parties who were not a party to said transaction. To control this we would require developers to authenticate prior to retrieving privileged information relating to a transaction.

Deposits

A deposit relates to two things: the adding of value into the Reservechain from the outside, and the creation of a new obligation to a user.

Given that this is a point in the chain at which there is a genesis of value, there are no subsequent transactions within the Reservechain to link backwards to. However, we will provide a link to the external authority documenting the source of the value whenever possible.

{
  "id": "e205b50e-6649-416d-82c1-98f0ba44dcd9",
  "type": "deposit",
  "params": {
    "currency": "BTC",
    "margin": "0.00",
    "pair": "BTCBTC",
    "rate": "1.00",
    "txid": "ffb51cc62944f334aa56ef7339a8df9ba08c712d9db609207f2f1f2105b914b2"
  },
  "denomination": {
    "amount": "0.5",
    "currency": "BTC"
  },
  "origin": {
    "amount": "0.5",
    "base": "0.5",
    "commission": "0.00",
    "currency": "BTC",
    "fee": "0.00",
    "rate": "1.00",
    "sources": []
  },
  "destination": {
    "amount": "0.5",
    "base": "0.5",
    "commission": "0.00",
    "currency": "BTC",
    "fee": "0.00",
    "rate": "1.00"
  },
  "status": "completed",
  "createdAt": "2014-10-08T12:26:29.807Z"
}

Withdrawals

Withdrawal documents the flow of assets out of the system. The destination of the transaction would refer as completely as it can to any external sources that the Bitreserve transaction can be correlated against/with.

Withdrawals also account for value leaving the Reservechain, and is thus a terminus point with regards to traceability.

{
  "id": "6ab1f3e8-3b84-40b0-aec7-8008117c9f86",
  "type": "withdrawal",
  "params": {
    "currency": "BTC",
    "margin": "0.00",
    "pair": "BTCBTC",
    "rate": "1.00",
    "txid": "5ee2a05a4af8bef5090ee8974798c097a7d6a75be7564d17e6a330bc1c434bab"
  },
  "denomination": {
    "amount": "34.00",
    "currency": "USD"
  },
  "origin": {
    "amount": "0.10359178",
    "base": "0.10349178",
    "commission": "0.00",
    "currency": "BTC",
    "fee": "0.0001",
    "rate": "1.00",
    "sources": [
      {
        "id": "33eef226-1c1e-4b38-be2f-28d9a57aecdb",
        "amount": "0.10359178"
      }
    ]
  },
  "destination": {
    "address": "1BSrDxeTL9ViJBrAb1QHjK2wsGShjSGVeb",
    "amount": "0.10349178",
    "base": "0.10349178",
    "commission": "0.00",
    "currency": "BTC",
    "fee": "0.00",
    "rate": "1.00",
  },
  "status": "completed",
  "createdAt": "2014-10-08T06:53:51.060Z"
}

Transfers

A transfer documents movement of value within our network, either between two parties or two denominations, or both.

{
  "id": "1571fbef-d34e-447c-9b6e-4ad775953082",
  "type": "transfer",
  "params": {
    "currency": "USD",
    "margin": "0.45",
    "pair": "BTCUSD",
    "rate": "392.16000",
    "txid": "1946783b396998f8f91c984431ecfecff6d0a72db68b32d0873c1024c7279254"
  },
  "denomination": {
    "amount": "1.3",
    "currency": "BTC"
  },
  "origin": {
    "amount": "1.3001",
    "base": "1.3",
    "commission": "0.00",
    "currency": "BTC",
    "fee": "0.0001",
    "rate": "0.00255",
    "sources": [
      {
        "id": "61cdccdf-cb6e-414e-aafc-7c42dc375cf6",
        "amount": "0.73327414"
      },
      {
        "id": "34f87520-49a4-4f46-8ee0-ba0522c06aa1",
        "amount": "0.56682586"
      }
    ]
  },
  "destination": {
    "amount": "507.51",
    "base": "509.81",
    "commission": "2.30",
    "currency": "USD",
    "fee": "0.00",
    "rate": "392.16000"
  },
  "status": "completed",
  "createdAt": "2014-09-30T20:29:36.458Z"
}

Privacy

The Reservechain is a public resource, and is 100% anonymous. At no point does the Reservechain expose any personally identifiable information, or any information that could be directly tied to an identity with our network.

We may disclose personally identifiable information to those who were a party to a transaction by way of the protected List User Transactions and List Card Transactions endpoints.

Pagination

Collection endpoints with large dataset supports Range Pagination Headers using Range & Content-Range entity-headers.

Request

You can provide the Range header specifying how many items you want to retrieve.

Here is an example:

curl "https://api.bitreserve.org/v0/me/transactions"
  -H "Authorization: Bearer <token>"
  -H "Range: items=0-4"

The above command will return the user’s last five transactions.

Response

The endpoints that support pagination returns a Content-Range header. For instance, if you make a request with Range: items=0-4 header the response will contain the following header: Content-Range 0-4/* where * will be the total number of items that this endpoint can return.

If the Range header is malformed or if the range cannot be satisfied you will receive a 412 error or a 416 error, respectively.

Rate Limits

The API applies rate limits based on the number of requests per a predefined interval (i.e. a time-window). We currently do not differentiate between authenticated and unauthenticated requests. The global rate limit takes into account the remote client IP only.

We plan on changing this policy in the future to one that limits on an account-by-account basis. For now, please be advised that those operating from corporate networks may hit their limit faster given that everyone may present the same IP address to our network.

Some endpoints have stricter rules as it relates to rate limits. These endpoints may additionally take into consideration the user’s account or email address. For example, there can be 10 requests per 10 minute time period per IP to the /password/forgot endpoint; but multiple IPs can only make 3 requests per 5 minute time period per user account (e.g. foo@bar.com).

The following table indicates the current rate limits:

Endpoint Requests (per IP) / window Requests (per user) / window
Global 300 / 5-min window N/A
POST /oauth2/token 10 / 1-min window 10 / 1-min window
POST /password/forgot 10 / 10-min window 3 / 5-min window
POST /users 10 / 10-min window N/A

Response Headers

The current rate limit in effect is explained via custom HTTP headers as described in the table below. Additionally, the standard HTTP Retry-After header field will be appended when the rate limit is exhausted and indicates, in delta-seconds, how long until the rate limit window is reset.

Header Description
X-RateLimit-Limit The total number of requests possible in the current window duration
X-RateLimit-Remaining The number of requests remaining in the current window duration
X-RateLimit-Reset The time, in UTC epoch seconds, until the end of the current window duration
Retry-After The time, in seconds, until the end of the current window duration

Example request:

curl -I -X GET "https://api.bitreserve.org/v0/ticker"

Rate limit details on response headers:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 299
X-RateLimit-Reset: 1422288284

When the API limit is reached, a status code of 429 Too Many Requests is returned with the aforementioned Retry-After header:

Example response for a rate limited request:

HTTP/1.1 429 Too Many Requests

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1422288284
Retry-After: 85

In this this example, the request could be retried in 1 minute and 25 seconds.

Alternatively, the X-RateLimit-Reset header could also be used to calculate when to retry the request:

Parsing X-RateLimit-Reset:

console.log(new Date(1422288199 * 1000));

// Mon Jan 26 2015 16:30:11 GMT+0000 (WET)

If you think you have a legitimate use-case for increased rate limits, please contact us.

Errors

Bitreserve API uses the following error codes:

Code Meaning
400 Bad Request – Validation failed.
401 Unauthorized – Bad credentials.
403 Forbidden – Access forbidden.
404 Not Found – Object not found.
412 Precondition Failed
416 Requested Range Not Satisfiable
429 Too Many Requests – Rate limit exceeded.
500 Internal Server Error – Something went wrong in our server.
503 Service Unavailable – We’re temporarily offline for maintenance. Please try again in a little bit.

Support

We are in the process of setting up a public forum for developers to seek support from the community and fellow Bitreserve professionals. In the meantime, if you have a question about the API, please contact us at support@bitreserve.org.