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.
- [Account](#account)
- [Get balances (A)](#get-balances-a)
- [Account operations](#account-operations)
- [Get the detail of an account operation (A)](#get-the-details-of-an-account-operation-a)
- [Get a list of account operations (A,P)](#get-a-list-of-account-operations-ap)
- [Send money](#send-money)
- [Send Bitcoins (A)](#send-bitcoins-a)
- [Send money to an e-mail address (A)](#send-money-to-an-e-mail-address-a)
- [Quotes](#quotes)
- [Create a quote (A)](#create-a-quote-a)
- [View a quote (A)](#view-a-quote-a)
- [List quotes (A,P)](#list-quotes)
- [Pay a quote (A)](#pay-a-quote-a)
- [Execute a quote (A)](#execute-a-quote-a)
- [Invoices](#invoices)
- [View an invoice (A)](#view-an-invoice-a)
- [View an invoice (Public)](#view-an-invoice-public)
- [List invoices (A,P)](#list-invoices-ap)
- [Create an invoice (A)](#create-an-invoice-a)
- [Payment buttons and creation through signed GET request](#payment-buttons-and-creation-through-signed-get-request)
- [Payment callbacks](#payment-callbacks)
- [Trading](#trading)
- [Place an order (A)](#place-an-order-a)
- [Cancel an order (A)](#cancel-an-order-a)
- [View trades for an order (A)](#view-trades-for-an-order-a)
- [View an order (A)](#view-an-order-a)
- [List active orders (A,P)](#list-active-orders-ap)
- [List all orders (A,P)](#list-all-orders-ap)
- [Read the ticker](#read-the-ticker)
- [Read the market depth](#read-the-market-depth)
- [Read historical trades](#read-historical-trades-p)
- [Coupons](#coupons)
- [Create a coupon (A)](#create-a-coupon-a)
- [View a coupon](#view-a-coupon)
- [Redeem a coupon (A)](#redeem-a-coupon-a)
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 :
Scope
Description
read
Read transaction history, balances and profile information
withdraw
Perform API calls that result in money being sent or withdrawn from the account
trade
Manage trade orders (create, read, cancel)
merchant
Manage invoices, read merchant dashboard and data
devices
Manage devices
In order to test OAuth2 integration a test app is available.
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.
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.
Parameter
Default
Acceptable values
page
1
Positive integer >0
per_page
20
Positive integer >=5 and <=100
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 :
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
Name
Type
Description
uuid
UUID
UUID of the account operation
Response
A JSON object with the following attributes is returned :
Name
Type
Description
uuid
UUID
UUID of the account operation
amount
Decimal
Amount of the operation (1)
currency
String
Currency of the operation (2)
created_at
Datetime
Timestamp of operation creation
state
String
Operation state if relevant, null otherwise (3)
type
String
Operation type (4)
balance
Decimal
Balance this operation led to
Credits are expressed as positive amounts, debits are expressed as negative amounts
See currencies table
See states table
See operation types table
Example request :GET /api/v1/account_operations/3a7bc1b2-9b7e-4dc3-9ffc-b3c08962ff4d
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
Name
Type
Description
amount
Decimal
Amount to send
currency
String
Currency in which the amount is expressed
address
String
Recipient's e-mail address
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
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 :
User scans Bitcoin QR code
Client app extracts requested Bitcoin amount
Client app requests a quote for this Bitcoin amount to the API and provides the currency in which debit upon quote payment
A guaranteed rate is returned by the API
Client app shows price expressed in the user's currency
After user confirmation the client app instructs the API to pay the quote to a specific Bitcoin address
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 :
How much BTC would need to be sold to get exactly 10 EUR
How much BTC could be bought with 10 EUR
How much EUR would the sale of 1 BTC get
How much EUR would be required to buy 1 BTC
To obtain the relevant quote a client would pass the following parameters :
Case
Currency
direction
requested_btc_amount
requested_currency_amount
1
EUR
sell
N/A
10
2
EUR
buy
N/A
10
3
EUR
sell
1
N/A
4
EUR
buy
1
N/A
Request path :/api/v1/quotes
Request method :POST
Request parameters
Name
Type
Description
requested_currency_amount
Decimal
Constrain on the currency amount (1)
requested_btc_amount
Decimal
Constrain on the Bitcoin amount (1)
direction
String
Whether the quote should apply to a sale or a purchase of Bitcoins (2)
currency
String
Currency in which the requested_amount is expressed
Exactly one of the currencies must be constrained, the other parameter may be omitted
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.
Name
Type
Description
uuid
UUID
Quote identifier
requested_currency_amount
Decimal
The instructed currency amount or null
requested_btc_amount
Decimal
The instructed Bitcoin amount or null
direction
String
The direction you provided
currency_amount
Decimal
The quoted currency amount or null
btc_amount
Decimal
The quoted Bitcoin amount or null
rate
Decimal
The quoted exchange rate
valid_until
Datetime
The timestamp at which this quote will be invalidated
created_at
Datetime
The creation date timestamp
executed
Boolean
Whether this quote has already been settled or paid
Example request :POST /api/v1/quotes
This demonstrates how to obtain a quote as described in the example use case #1.
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
Name
Type
Description
uuid
UUID
Quote identifier
address
String
Valid Bitcoin address
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
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
Name
Type
Description
uuid
UUID
Quote identifier
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
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
Name
Type
Description
uuid
UUID
Quote identifier
Response
A JSON object with the following parameters is returned.
Name
Type
Description
uuid
UUID
Invoice identifier
state
String
Invoice state (see appendix)
payment_address
String
Bitcoin payment address
payment_bitcoin_\uri
String
Payment URI, should be used to generate QR codes
amount
Decimal
Requested amount to be credited upon payment
btc_amount
Decimal
Payable amount expressed in BTC
amount_to_pay
Decimal
Amount left to pay
btc_amount_to_pay
Decimal
Bitcoin amount amount left to pay
currency
String
Currency in which the amount is expressed
merchant_reference
String
Merchant reference
merchant_memo
String
Merchant memo
callback_url
String
URL to which a callback should be made when the invoice is paid
item_url
String
Order-related URL
paid_at
Datetime
Payment timestamp
created_at
Datetime
Creation timestamp
updated_at
Datetime
Update timestamp
expires_at
Datetime
Expiration timestamp
settled
Boolean
Has this invoice already been credited ?
notification_email_sent
Boolean
Has the notification e-mail already been sent ?
public_url
String
The URL at which this invoice is publicly visible and payable
Example request :GET /api/v1/invoices/70c7936b-f8ce-443a-8338-3762de0a1e92
请发表评论