Difference between revisions of "Prime API"

From Bitcoin Wiki
Jump to: navigation, search
(Created page with "Prime API is based on JSON, delivered through HTTPS and is mostly REST-ful. ==Public API== Public API calls are available without authentication. ==Private API== Private A...")
 
 
(6 intermediate revisions by the same user not shown)
Line 1: Line 1:
 +
==Introduction==
 +
 
Prime API is based on JSON, delivered through HTTPS and is mostly REST-ful.
 
Prime API is based on JSON, delivered through HTTPS and is mostly REST-ful.
 +
 +
API URIs always start with a marker "/v1" to make the version explicit.
 +
 +
All timestamps are returned in ISO 8601 format:
 +
 +
YYYY-MM-DDTHH:MM:SSZ
  
 
==Public API==
 
==Public API==
Line 8: Line 16:
  
 
Private API calls require authentication via:
 
Private API calls require authentication via:
−
* API key and optionally
+
* Your personal API key and optionally
 
* IP address
 
* IP address
  
 
Private API is '''off by default'''. You need to enable it in your profile.
 
Private API is '''off by default'''. You need to enable it in your profile.
 +
 +
You are expected to '''pass the API key as a HTTP header''':
 +
Authorization: PrimeExchange 84ffsOscok1Asbbqj28gcscv86M3nj4bRIamFaKe
 +
...where the long string is of course your API key.
 +
 +
It is also possible to pass the API key as a request param:
 +
?api_key=84ffsOscok1Asbbqj28gcscv86M3nj4bRIamFaKe
 +
...although this is not recommended as sensitive data should not be passed in the URI.
 +
 +
===Get my deposit address===
 +
 +
GET /v1/prv/deposit_address/:currency_name.json
 +
* '''currency_name''' - obligatory cryptocurrency name, i.e BTC, LTC
 +
 +
Example:
 +
<source lang="bash">
 +
curl -v --request GET http://localhost:3000/v1/prv/deposit_address/BTC.json --header "Authorization: PrimeExchange 84ffsOscok1Asbbqj28gcscv86M3nj4bRIamFaKe"
 +
</source>
 +
 +
Response:
 +
200 OK
 +
<source lang="javascript">
 +
{"address":"n2Ccn5em9gcQyBe2QvZnfzzXq8EZh1ncJj"}
 +
</source>
 +
 +
Error response:
 +
422 Unprocessable Entity
 +
<source lang="javascript">
 +
{"errors":{"currency_name":"is invalid"}}
 +
</source>
 +
 +
===Get balances and user data===
 +
 +
GET /v1/prv/user.json
 +
 +
Example:
 +
<source lang="bash">
 +
curl -i --request GET http://localhost:3000/v1/prv/user.json --header "Authorization: PrimeExchange 84ffsOscok1Asbbqj28gcscv86M3nj4bRIamFaKe"
 +
</source>
 +
 +
Response:
 +
200 OK
 +
<source lang="javascript">
 +
{
 +
  "user": {
 +
    "username": "adalovelace",
 +
    "email": "adalovelace@bitcoinfoundation.org",
 +
    "balances": [
 +
      {
 +
        "available": "0.199",
 +
        "total": "0.199",
 +
        "currency_name": "BTC"
 +
      },
 +
      {
 +
        "available": "0.0",
 +
        "total": "0.0",
 +
        "currency_name": "PLN"
 +
      },
 +
      {
 +
        "available": "7.11",
 +
        "total": "7.11",
 +
        "currency_name": "LTC"
 +
      }
 +
    ]
 +
  }
 +
}
 +
</source>
 +
* '''available''' - the amount you can manage, i.e. to place a new offer
 +
* '''total''' - the amount including funds reserved for offers, withdrawals, etc.
 +
 +
 +
===Create a withdrawal request (of cryptocurrency)===
 +
 +
POST /v1/prv/withdrawal_request.json
 +
* '''currency_name''' - obligatory name of the currency like BTC, LTC, PLN
 +
* '''address''' - obligatory only for cryptocurrencies
 +
* '''amount''' - obligatory
 +
* '''otp''' - obligatory when user has set up a Google Authenticator One-Time-Passwords for withdrawals
 +
 +
Example:
 +
<source lang="bash">
 +
curl -i --request POST http://localhost:3000/v1/prv/withdrawal_requests.json --header "Authorization: PrimeExchange 84ffsOscok1Asbbqj28gcscv86M3nj4bRM6sLRdM" \
 +
--data "currency_name=BTC&address=mm2SjeJ64vQokDjnkhvhcv9mGk1VfEJRsk&amount=0.03"
 +
</source>
 +
 +
Response:
 +
201 Created
 +
 +
Error response (missing or invalid OTP):
 +
401 Unauthorized
 +
<source lang="javascript">
 +
{
 +
  "errors": {
 +
    "otp": "is invalid"
 +
  }
 +
}
 +
</source>
 +
 +
Error response (invalid params):
 +
422 Unprocessable Entity
 +
<source lang="javascript">
 +
{
 +
  "errors": {
 +
    "currency_name": "is invalid",
 +
    "address": "is_invalid",
 +
    "amount": "is invalid"
 +
  }
 +
}
 +
</source>
 +
 +
==References==
 +
<References />

Latest revision as of 22:37, 7 February 2014

Introduction

Prime API is based on JSON, delivered through HTTPS and is mostly REST-ful.

API URIs always start with a marker "/v1" to make the version explicit.

All timestamps are returned in ISO 8601 format: 

YYYY-MM-DDTHH:MM:SSZ

Public API

Public API calls are available without authentication.

Private API

Private API calls require authentication via:

  • Your personal API key and optionally
  • IP address

Private API is off by default. You need to enable it in your profile.

You are expected to pass the API key as a HTTP header: 

Authorization: PrimeExchange 84ffsOscok1Asbbqj28gcscv86M3nj4bRIamFaKe

...where the long string is of course your API key.

It is also possible to pass the API key as a request param: 

?api_key=84ffsOscok1Asbbqj28gcscv86M3nj4bRIamFaKe

...although this is not recommended as sensitive data should not be passed in the URI.

Get my deposit address

GET /v1/prv/deposit_address/:currency_name.json
  • currency_name - obligatory cryptocurrency name, i.e BTC, LTC

Example: 

curl -v --request GET http://localhost:3000/v1/prv/deposit_address/BTC.json --header "Authorization: PrimeExchange 84ffsOscok1Asbbqj28gcscv86M3nj4bRIamFaKe"

Response: 

200 OK

 {"address":"n2Ccn5em9gcQyBe2QvZnfzzXq8EZh1ncJj"}

Error response: 

422 Unprocessable Entity

 {"errors":{"currency_name":"is invalid"}}

Get balances and user data

GET /v1/prv/user.json

Example: 

curl -i --request GET http://localhost:3000/v1/prv/user.json --header "Authorization: PrimeExchange 84ffsOscok1Asbbqj28gcscv86M3nj4bRIamFaKe"

Response: 

200 OK

{
  "user": {
    "username": "adalovelace",
    "email": "adalovelace@bitcoinfoundation.org",
    "balances": [
      {
        "available": "0.199",
        "total": "0.199",
        "currency_name": "BTC"
      },
      {
        "available": "0.0",
        "total": "0.0",
        "currency_name": "PLN"
      },
      {
        "available": "7.11",
        "total": "7.11",
        "currency_name": "LTC"
      }
    ]
  }
}
  • available - the amount you can manage, i.e. to place a new offer
  • total - the amount including funds reserved for offers, withdrawals, etc.


Create a withdrawal request (of cryptocurrency)

POST /v1/prv/withdrawal_request.json
  • currency_name - obligatory name of the currency like BTC, LTC, PLN
  • address - obligatory only for cryptocurrencies
  • amount - obligatory
  • otp - obligatory when user has set up a Google Authenticator One-Time-Passwords for withdrawals

Example: 

curl -i --request POST http://localhost:3000/v1/prv/withdrawal_requests.json --header "Authorization: PrimeExchange 84ffsOscok1Asbbqj28gcscv86M3nj4bRM6sLRdM" \
--data "currency_name=BTC&address=mm2SjeJ64vQokDjnkhvhcv9mGk1VfEJRsk&amount=0.03"

Response: 

201 Created

Error response (missing or invalid OTP): 

401 Unauthorized

{
  "errors": {
    "otp": "is invalid"
  }
}

Error response (invalid params): 

422 Unprocessable Entity

{
  "errors": {
    "currency_name": "is invalid",
    "address": "is_invalid",
    "amount": "is invalid"
  }
}

References

Retrieved from "https://en.bitcoin.it/w/index.php?title=Prime_API&oldid=44325"