开源软件名称：

开源软件地址：

开源编程语言：

开源软件介绍：

This document describes the API calls available as part of the Paytunia v1 API.

The API is shared by both Bitcoin-Central.net and Paytunia.com. Both apps run against the same database, therefore using the API against one of them is equivalent to using the API against the other.

If your language of choice is Ruby we recommend using the Paytunia gem instead of writing your own client.

Table of contents

• General API description

• API Calls

• Appendix
  • Codes and types tables

    • Currencies

    • Operation types

    • States

      • Transfer (Bitcoin transfer, Wire transfers) statuses
      • Coupon statuses
      • E-mail transfer statuses
      • Invoice statuses
      • Trade order statuses

General API description

Authentication

Calls that require authentication are marked with "A" in the call description title.

Authentication and authorization may be done with :

• HTTP Basic
• OAuth2

OAuth2 is useful when it is not desirable for client apps to handle the user's credentials directly or when it is necessary to have access to an account with limited privileges.

Each API call description mentions the OAuth2 scope required to use it.

The available OAuth2 scopes are :

In order to test OAuth2 integration a test app is available.

After authorization the authorization token will be directly displayed in your browser (that's what the special test callback URL is for).

Example authorization link : https://bitcoin-central.net/oauth/authorize?client_id=6...pe=code

Full usage example :

This example uses the OAuth2 Ruby gem.

require 'oauth2'

client = OAuth2::Client.new('6fcf1c32f6e14cd773a7a6640832bdbf83a5b2b8d4382e839c6aff83a8f1bb3b', '55554ecad5627f0465034c4a116e59a38d9c3ab272487a18404078ccc0b64798', site: 'https://bitcoin-central.net')
 
client.auth_code.authorize_url(redirect_uri: 'urn:ietf:wg:oauth:2.0:oob', scope: 'read trade')
 => "https://bitcoin-central.net/oauth/authorize?response_type=code&client_id=6fcf1c32f6e14cd773a7a6640832bdbf83a5b2b8d4382e839c6aff83a8f1bb3b&redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob&scope=read+trade" 

# Visit this URL in your browser, approve the request and copy the authorization code

authorization_code = '...'

token = client.auth_code.get_token(authorization_code, redirect_uri: 'urn:ietf:wg:oauth:2.0:oob')

token.get('/api/v1/trade_orders/active').body

=> [{"uuid":"148ab996-ab63-45cc-b240-99c78bb18a11","instructed_amount":300.0,"amount":268.70563158,"state":"active","created_at":"2013-02-07T19:09:44+01:00","updated_at":"2013-02-14T13:12:00+01:00","price":15.9199,"type":"buy"}]

If you encounter SSL certificate errors while trying this example it's probably because your Ruby install doesn't know where to find the CA certificates. In development you can use an incredibly ugly hack to temporarily skip SSL certificate validation : OpenSSL::SSL::VERIFY_PEER = OpenSSL::SSL::VERIFY_NONE. You should never do this in production.

Base URL

The base URL for all calls is https://bitcoin-central.net. A complete URL would look like this https://bitcoin-central.net/api/v1/quotes/3a7bc1b2-9b7e-4dc3-9ffc-b3c08962ff4d.

Formats and required HTTP request headers

The API will only answer with JSON or empty responses. It expects parameters to be passed in JSON with the correct Content-Type: application/json being set.

Rate-limiting

API calls are rate-limited by IP to 5000 calls per day. Information about the status of the limit can be found in the X-RateLimit-Limit and X-RateLimit-Remaining HTTP headers.

Example response with rate-limit headers

HTTP/1.1 200  
Content-Type: application/json; charset=utf-8
X-Ratelimit-Limit: 5000
X-Ratelimit-Remaining: 4982
Date: Wed, 30 Jan 2013 12:08:58 GMT

Pagination

Some API calls returning collections may be paginated. In this case the call description title mentions it.

Calls that return paginated data are marked with "P" in the call description title.

HTTP response header

Calls that return paginated collections will add a Pagination HTT header to the response. It will contain a pagination meta-data JSON object.

Pagination header example

{
  // Whether the current page is the first of the collection
  "first_page": true,

  // Total amount of available pages
  "total_pages": 1,

  // Previous page number
  "previous_page": null,

  // Total number of items in the collection
  "total": 1,

  // Next page number
  "next_page": null,

  // Whether the current page is the last available one
  "last_page": true,

  // Record collection offset
  "offset": 0
}

Controlling pagination

Optional pagination parameters may be passed in the request URI in order to control the way the collection gets paginated. If parameters are incorrect a HTTP 400 Bad request status is returned along with an empty body.

Localization

The relevant results and error messages will be localized to the language associated to the user, currently English and French are supported.

Datetime formats

Datetime values will be returned as regular JSON format and Unix timestamps, the timestamps are suffixed with _int.

Error handling

Whenever an error is encountered, the answer to a JSON API call will have :

• An HTTP 422 status (Unprocessable entity) or HTTP 400 (Bad request),
• A JSON array of localized error messages as body

Successful calls

If the API call was successful, the platform will answer with :

• An HTTP 200 status (OK) or HTTP 201 (Created),
• A JSON representation of the entity being created or updated if relevant

API Calls

Account

Get balances (A)

This call will return the balances in all currencies.

This call requires the read OAuth2 scope.

Request path : /api/v1/balances

Request method : GET

Request parameters

None

Response

A JSON object with the following attributes is returned :

Example request : GET /api/v1/balances

Example response :

{
  "EUR" : 1.0,
  "BTC" : 1.42,
  "USD" : 0.0,
  "GBP" : 0.0
}

Account operations

An account operation is any ledger operation that changes the account's balance.

These calls require the read OAuth2 scope.

Get the details of an account operation (A)

This call will return the details of a single account operation, the response contains : the UUID identifying the operation, the amount of this particular operation, its currency, its creation timestamp, its state (if relevant), a string indicating the type of the operation and the account balance that this operation led to (the sum of all transactions in the same currency including this one but not the ones that came after it).

Request path : /api/v1/account_operations/{uuid}

Request method : GET

Request parameters

Response

A JSON object with the following attributes is returned :

1. Credits are expressed as positive amounts, debits are expressed as negative amounts
2. See currencies table
3. See states table
4. See operation types table

Example request : GET /api/v1/account_operations/3a7bc1b2-9b7e-4dc3-9ffc-b3c08962ff4d

Example response :

{
  "uuid" : "3a7bc1b2-9b7e-4dc3-9ffc-b3c08962ff4d",
  "amount" : 50.0,
  "currency" : "EUR",
  "created_at" : "2013-01-14T16:28:57Z",
  "created_at_int" : 1363858355,      
  "state" : null,
  "type" : "wire_deposit",
  "balance" : 550.0
}

Get a list of account operations (A,P)

This call will return a paginated list of account operations relative to the authenticated account.

Request path : /api/v1/account_operations

Request method : GET

Request parameters

None

Response

A JSON array of account operations is returned. The structure collection elements is detailed at "Get the details of an account operation".

Example request : GET /api/v1/account_operations

Example response :

[ 
  {
    "uuid" : "3a7bc1b2-9b7e-4dc3-9ffc-b3c08962ff4d",
    "amount" : 50.0,
    "currency" : "EUR",
    "created_at" : "2013-01-14T16:28:57Z",
    "created_at_int" : 1363858355,        
    "state" : null,
    "type" : "wire_deposit",
    "balance" : 550.0
  },
  {
    "uuid" : "b3c08962-4dc3-9ffc-4dc3-3a7bc1b2ff4d",
    "amount" : 500.0,
    "currency" : "EUR",
    "created_at" : "2013-01-10T12:45:50Z",
    "created_at_int" : 1363858355,        
    "state" : null,
    "type" : "wire_deposit",
    "balance" : 500.0
  }      
]

Send money

These calls require the withdraw OAuth2 scope.

Send Bitcoins (A)

This call will perform a Bitcoin transaction.

Request path : /api/v1/transfers/send_bitcoins

Request method : POST

Request parameters

Response

An UUID is returned after the request is queued for execution. It enables the client to make subsequent status check requests.

Example request : POST /api/v1/transfers/send_bitcoins

{
  "amount" : 10.0,
  "address" : "1KfNzSKFAmpC4kNYaGLqj8LGPHxGmRG2nZ"
}

Example response :

{
  "uuid" : "3a7bc1b2-9b7e-4dc3-9ffc-b3c08962ff4d"     
}

Send money to an e-mail address (A)

This call will move money to the account identified with the given e-mail address. If no such account is found an e-mail gets sent inviting its recipient to create an account, or sign-in to one to retrieve the sent funds. If the amount isn't claimed after a week the funds are returned to the sender.

Request path : /api/v1/transfers/send_to_email

Request method : POST

Request parameters

Response

An UUID is returned after the request is queued for execution. It enables the client to make subsequent status check requests.

Example request : POST /api/v1/transfers/send_bitcoins

{
  "amount" : 10.0,
  "currency" : "EUR",
  "address" : "[email protected]"
}

Example response :

{
  "uuid" : "3a7bc1b2-9b7e-4dc3-9ffc-b3c08962ff4d"     
}

Quotes

Quotes are a mechanism for clients to send funds or exchange them to other currencies. They provide clients with a guaranteed fixed-rate at which the system will convert their funds before crediting them to their account or send them out.

The canonical use of a quote is to pay in currency to a Bitcoin invoice, materialized as a QR code :

1. User scans Bitcoin QR code
2. Client app extracts requested Bitcoin amount
3. Client app requests a quote for this Bitcoin amount to the API and provides the currency in which debit upon quote payment
4. A guaranteed rate is returned by the API
5. Client app shows price expressed in the user's currency
6. After user confirmation the client app instructs the API to pay the quote to a specific Bitcoin address
7. The merchant receives the payment in Bitcoin and the user is debited in his native currency

These calls require the trade OAuth2 scope, the Pay a quote action requires the withdraw scope.

Create a quote (A)

This call will create a quote. When doing so clients must specify a currency (the other currency is always assumed to be "BTC") an amount they are requesting and a direction. Combining these parameters in various ways will have the system address a wide array of use cases.

For example a client can request :

1. How much BTC would need to be sold to get exactly 10 EUR
2. How much BTC could be bought with 10 EUR
3. How much EUR would the sale of 1 BTC get
4. How much EUR would be required to buy 1 BTC

To obtain the relevant quote a client would pass the following parameters :

Request path : /api/v1/quotes

Request method : POST

Request parameters

1. Exactly one of the currencies must be constrained, the other parameter may be omitted
2. Acceptable values are buy and sell

Response

A JSON object with the following parameters is returned. If the current market depth or volatility does not allow for a quote to be given an error will be returned.

Example request : POST /api/v1/quotes

This demonstrates how to obtain a quote as described in the example use case #1.

{
  "requested_amount" : 10.0,
  "currency" : "EUR",
  "direction" : "sell"
}

Example response :

{
  "uuid" : "3a7bc1b2-9b7e-4dc3-9ffc-b3c08962ff4d",
  "currency" : "EUR",
  "direction" : "sell",
  "rate" : 10.65
  "currency_amount" : null,
  "btc_amount" : 0.93896714
  "requested_currency_amount" : 10,
  "requested_btc_amount" : null,
  "valid_until" : "2013-01-10T13:00:50Z",
  "created_at" : "2013-01-10T12:45:50Z",
  "created_at_int" : 1363858355,      
  "executed" : false
}

View a quote (A)

This call will return a JSON object representing a quote

Request path : /api/v1/quotes/{uuid}

Request method : GET

Request parameters

Response

A JSON object with the following parameters is returned.

Example request : GET /api/v1/quotes/3a7bc1b2-9b7e-4dc3-9ffc-b3c08962ff4d

Example response :

{
  "uuid" : "3a7bc1b2-9b7e-4dc3-9ffc-b3c08962ff4d",
  "currency" : "EUR",
  "direction" : "sell",
  "rate" : 10.65
  "currency_amount" : null,
  "btc_amount" : 0.93896714
  "requested_currency_amount" : 10,
  "requested_btc_amount" : null,
  "valid_until" : "2013-01-10T13:00:50Z",
  "created_at" : "2013-01-10T12:45:50Z",
  "created_at_int" : 1363858355,            
  "executed" : false
}

List quotes (A,P)

This call will return a paginated list of quotes for the client account.

Request path : /api/v1/quotes

Request method : GET

Request parameters

N/A

Response

A JSON array of quote objects is returned.

Example request : GET /api/v1/quotes

Example response :

[
  {
    "uuid" : "3a7bc1b2-9b7e-4dc3-9ffc-b3c08962ff4d",
    "currency" : "EUR",
    "direction" : "sell",
    "rate" : 10.65
    "currency_amount" : null,
    "btc_amount" : 0.93896714
    "requested_currency_amount" : 10,
    "requested_btc_amount" : null,
    "valid_until" : "2013-01-10T13:00:50Z",
    "created_at" : "2013-01-10T12:45:50Z",
    "created_at_int" : 1363858355,              
    "executed" : true
  },
  {
    "uuid" : "4dc33a7bc1b2-9b7e-3a7b-9ffc-b3c08962ff4d",
    "currency" : "EUR",
    "direction" : "sell",
    "rate" : 10.65
    "currency_amount" : null,
    "btc_amount" : 0.93896714
    "requested_currency_amount" : 10,
    "requested_btc_amount" : null,
    "valid_until" : "2013-01-10T13:00:50Z",
    "created_at" : "2013-01-10T12:45:50Z",
    "created_at_int" : 1363858355,                      
    "executed" : true
  }
]

Pay a quote (A)

This action applies only to quotes for buying BTC.

It will perform the exchange creating a user account debit of the calculated currency_amount or instructed requested_currency_amount and send out the calculated btc_amount or instructed requested_btc_amount to the Bitcoin address in the address field.

Calling this method queues the quote for payment if possible. The quote status can later be queried using the view a quote call.

Request path : /api/v1/quotes/{uuid}/pay

Request method : POST

Request parameters

Response

The quote as it was when the payment was requested is returned.

Example request : GET /api/v1/quotes/3a7bc1b2-9b7e-4dc3-9ffc-b3c08962ff4d/pay

Example response :

{
  "uuid" : "3a7bc1b2-9b7e-4dc3-9ffc-b3c08962ff4d",
  "currency" : "EUR",
  "direction" : "sell",
  "rate" : 10.65
  "currency_amount" : null,
  "btc_amount" : 0.93896714
  "requested_currency_amount" : 10,
  "requested_btc_amount" : null,
  "valid_until" : "2013-01-10T13:00:50Z",
  "created_at" : "2013-01-10T12:45:50Z",
  "created_at_int" : 1363858355,                    
  "executed" : false
}

Execute a quote (A)

This action applies to quotes for buying and selling BTC. It will perform the exchange creating user account debit and credit operations depending on the quote requested.

Calling this method queues the quote for execution if possible. The quote status can later be queried using the view a quote call.

Request path : /api/v1/quotes/{uuid}/execute

Request method : POST

Request parameters

Response

The quote as it was when the execution was requested is returned.

Example request : POST /api/v1/quotes/3a7bc1b2-9b7e-4dc3-9ffc-b3c08962ff4d/execute

Example response :

{
  "uuid" : "3a7bc1b2-9b7e-4dc3-9ffc-b3c08962ff4d",
  "currency" : "EUR",
  "direction" : "sell",
  "rate" : 10.65
  "currency_amount" : null,
  "btc_amount" : 0.93896714
  "requested_currency_amount" : 10,
  "requested_btc_amount" : null,
  "valid_until" : "2013-01-10T13:00:50Z",
  "created_at" : "2013-01-10T12:45:50Z",
  "created_at_int" : 1363858355,                    
  "executed" : false
}

Invoices

Invoices are requests for payment. They can be expressed in any arbitrary currency. They all get a unique Bitcoin payment address assigned and a Bitcoin amount calculated from the requested currency amount.

Payment can be made by sending the btc_amount amount of Bitcoins to the payment_address address or directly in the requested currency from another account. The invoice payment will trigger a POSTto the callback_url.

These calls require the merchant OAuth2 scope.

View an invoice (A)

This call will return a JSON object representing an invoice

Request path : /api/v1/invoices/{uuid}

Request method : GET

Request parameters

Response

A JSON object with the following parameters is returned.

Example request : GET /api/v1/invoices/70c7936b-f8ce-443a-8338-3762de0a1e92

Example response :

{
  "uuid": "70c7936b-f8ce-443a-8338-3762de0a1e92",    
  "amount": 10.0, 
  "amount_to_pay": 10.0,
  "btc_amount": 1.021732,
  "btc_amount_to_pay": 1.021732, 
  "notification_email_sent": false, 
  "callback_url": null, 
  "created_at": "2013-01-21T10:20:07Z", 
  "created_at_int" : 1363858355,                    
  "currency": "EUR", 
  "expires_at": "2013-01-21T10:40:07Z", 
  "item_url": null, 
  "merchant_memo": null, 
  "merchant_reference": null, 
  "paid_at": null, 
  "payment_address": "1JnjJNhdKSgvMKr6xMbqVEudB3eACsGJSz", 
  "payment_bitcoin_uri" : "bitcoin:1JnjJNhdKSgvMKr6xMbqVEudB3eACsGJSz?amount=100.0&label=&x-pay-curamt=100.0&x-pay-cur=BTC&x-pay-id=7653453d-6372-4ffa-bc56-1e3182ef7f35",       
  "settled": false,