REST API Documentation¶
CryptoToken Converter exposes a REST API under the URL /api
to allow any application
to easily interact with the system.
It uses Django REST Framework which automatically generates a lot of the code running behind the API endpoints.
Endpoints¶
For GET requests, any request parameters must either be sent as either:
Standard GET parameters - e.g.
/api/deposits/?from_address=someguy123
Directly in the URL - e.g.
/api/coins/LTC
For POST requests, you may send your request data/params as a normal URL encoded form, or you may choose to send it as JSON.
application/json - JSON Encoded Body
{ "my_param": "somevalue", "other.param": "other value" }application/x-www-form-urlencoded - Standard POST body
my_param=somevalue&other.param=other%20value
/api/convert/¶
Starts the conversion process between two coins.
Returns the deposit details for you to send the coins to.
Methods: POST (URL Encoded Form, or JSON)
POST Parameters:
Parameter | Type | Description |
---|---|---|
from_coin | String | Symbol of the coin to convert from |
to_coin | String | Symbol of the destination coin |
destination | String | The address or account on to_coin for receiving
your converted coins |
All parameters are required.
Errors:
If the JSON response
error
key is present and set totrue
, the error message will be placed inmessage
, and a non-200 status code will be returned, related to the error reason.Potential errors and their status codes:
- “An unknown error has occurred… please contact support”, 500
- “You must specify ‘from_coin’, ‘to_coin’, and ‘destination’”, 400
- “There is no such coin pair {} -> {}”, 404
- “The destination {} address/account ‘{}’ is not valid”, 400
Example error response:
POST /api/convert/ HTTP 400 Bad Request Allow: POST, OPTIONS Content-Type: application/json Vary: Accept { "error": true, "message": "You must specify 'from_coin', 'to_coin', and 'destination'" }
Return Data:
All successful requests will include
ex_rate
(the amount ofto_coin
perfrom_coin
),pair
(details about the coin pair that you have chosen), anddestination
(where thefrom_coin
will be sent to).Depending on whether the
from_coin
is an address based coin, or an account/memo based coin, the actual deposit details will be returned differently. Address based coins will returnaddress
, while account based coins will returnaccount
andmemo
.Below are two examples to help explain this.
SGTK
is “Sometoken”, a SteemEngine token, meaning it’s account+memo based.LTC
is Litecoin, a classic address based cryptocurrency.Example 1 (address based -> account based):
POST /api/convert/ from_coin=LTC&to_coin=SGTK&destination=someguy123 HTTP 200 OK Content-Type: application/json { "ex_rate": 100000.0, "destination": "someguy123", "pair": "LTC -> SGTK (100000.0000 SGTK per LTC)", "address": "MJL1E5oSqFLpdL9BswKmYonxU1Cq1WKWGL" }Example 2 (account based -> address based):
POST /api/convert/ from_coin=SGTK&to_coin=LTC&destination=MVYBriQcasb6zvtGjPfLKbbWcRoKWh4sAf HTTP 200 OK Content-Type: application/json { "ex_rate": 0.01, "destination": "MVYBriQcasb6zvtGjPfLKbbWcRoKWh4sAf", "pair": "SGTK -> LTC (0.0100 LTC per SGTK)", "memo": "LTC MVYBriQcasb6zvtGjPfLKbbWcRoKWh4sAf", "account": "someguy123" }
/api/deposits/¶
/api/deposits/
- Returns all deposit attempts received by the system. Can be filtered using the GET Parameters listed below.
/api/deposits/<id>
- Returns a single deposit attempt by it’s ID
Methods: GET
GET Parameters:
These parameters can be used with the plain /api/deposits/
URL, to filter deposits based on various columns.
Note: Results from /api/deposits/
will always be returned as a list, even if there’s only one.
Parameter | Type | Description |
---|---|---|
address | String | Return deposits that were sent to this address (only for address-based coins) |
txid | String | Return deposits with a matching transaction ID |
from_account | String | Return deposits that were sent from this account (only for account-based coins) |
to_account | String | Return deposits that were sent to this account (only for account-based coins) |
memo | String | Return deposits that were sent using this memo (normally only for account-based coins) |
Return Data:
Example 1 (Plain GET request):
GET /api/deposits/ HTTP 200 OK Content-Type: application/json [ { "id": 4, "txid": "635dd656b3bd8c61699e6066c9b3c6e74696e195", "coin": "http://127.0.0.1:8000/api/coins/SGTK/", "vout": 0, "status": "conv", "tx_timestamp": "2019-03-20T03:46:30Z", "address": null, "from_account": "privex", "to_account": "someguy123", "amount": "1.00000000000000000000", "memo": "LTC LKjpPtgMbcFgbJJYwzfe1ZtR8x4bbs2V3o", "processed_at": "2019-03-20T04:31:30.643406Z", "convert_to": "http://127.0.0.1:8000/api/coins/LTC/" }, { "id": 5, "txid": "b881d1ae8cf280184960c9c2d74bc1bd230f18f5adcd7fe695239dbf46b06c45", "coin": "http://127.0.0.1:8000/api/coins/LTC/", "vout": 0, "status": "conv", "tx_timestamp": "2019-03-20T01:34:20Z", "address": "MFht1FmYhsRaSChGdqomxQpjtGtsjFHDQX", "from_account": null, "to_account": null, "amount": "0.10000000000000000000", "memo": null, "processed_at": "2019-03-20T04:46:53.602857Z", "convert_to": "http://127.0.0.1:8000/api/coins/SGTK/" } ]Example 2 (Filtering results):
GET /api/deposits/?txid=635dd656b3bd8c61699e6066c9b3c6e74696e195 HTTP 200 OK Content-Type: application/json [ { "id": 4, "txid": "635dd656b3bd8c61699e6066c9b3c6e74696e195", "coin": "http://127.0.0.1:8000/api/coins/SGTK/", "vout": 0, "status": "conv", "tx_timestamp": "2019-03-20T03:46:30Z", "address": null, "from_account": "privex", "to_account": "someguy123", "amount": "1.00000000000000000000", "memo": "LTC LKjpPtgMbcFgbJJYwzfe1ZtR8x4bbs2V3o", "processed_at": "2019-03-20T04:31:30.643406Z", "convert_to": "http://127.0.0.1:8000/api/coins/LTC/" } ]Example 3 (ID Lookup):
GET /api/deposits/4/ HTTP 200 OK Content-Type: application/json { "id": 4, "txid": "635dd656b3bd8c61699e6066c9b3c6e74696e195", "coin": "http://127.0.0.1:8000/api/coins/SGTK/", "vout": 0, "status": "conv", "tx_timestamp": "2019-03-20T03:46:30Z", "address": null, "from_account": "privex", "to_account": "someguy123", "amount": "1.00000000000000000000", "memo": "LTC LKjpPtgMbcFgbJJYwzfe1ZtR8x4bbs2V3o", "processed_at": "2019-03-20T04:31:30.643406Z", "convert_to": "http://127.0.0.1:8000/api/coins/LTC/" }
/api/conversions/¶
/api/conversions/
- Returns all successful conversions sent by the system. Can be filtered using the GET Parameters listed below.
/api/conversions/<id>
- Returns a single conversion by it’s ID
Methods: GET
GET Parameters:
These parameters can be used with the plain /api/conversions/
URL, to filter conversions based on various columns.
Note: Results from /api/conversions/
will always be returned as a list, even if there’s only one.
Parameter | Type | Description |
---|---|---|
to_address | String | Return conversions that were sent to this address or account (it’s used for both) |
to_txid | String | Return conversions with this outgoing TXID |
to_coin | String | Return conversions into this coin symbol |
from_coin | String | Return conversions from this coin symbol |
from_address | String | Return conversions that were sent from this address or account (it’s used for both) |
Return Data:
Note: The
to_amount
is the final amount that the user should have received AFTERex_fee
andtx_fee
were removed.Example 1 (Plain GET request):
GET /api/conversions/ HTTP 200 OK Content-Type: application/json [ { "url": "http://127.0.0.1:8000/api/conversions/6/", "from_address": "LKjpPtgMbcFgbJJYwzfe1ZtR8x4bbs2V3o", "to_address": "LKjpPtgMbcFgbJJYwzfe1ZtR8x4bbs2V3o", "to_memo": "Token Conversion from SGTK account privex", "to_amount": "0.00883200000000000000", "to_txid": "e4a5cb3ccc5524e20a39b1a076cef16a85efc68bf929e7a3ec4a834c30711e55", "tx_fee": "0.00016800000000000000", "ex_fee": "0.00100000000000000000", "created_at": "2019-03-21T10:14:20.021360Z", "updated_at": "2019-03-21T10:14:20.021373Z", "deposit": "http://127.0.0.1:8000/api/deposits/10/", "from_coin": "http://127.0.0.1:8000/api/coins/SGTK/", "to_coin": "http://127.0.0.1:8000/api/coins/LTC/" }, { "url": "http://127.0.0.1:8000/api/conversions/7/", "from_address": "someguy123", "to_address": "privex", "to_memo": "Token Conversion via LTC deposit address MTcPHSipXBzwhTWT8wXMtNf6vwAxovjpx9", "to_amount": "900.00000000000000000000", "to_txid": "55c30e43088c8aa6d7a74da1e29d3843cd7157e7", "tx_fee": "0.00000000000000000000", "ex_fee": "100.00000000000000000000", "created_at": "2019-03-21T10:15:47.071323Z", "updated_at": "2019-03-21T10:15:47.071340Z", "deposit": "http://127.0.0.1:8000/api/deposits/9/", "from_coin": "http://127.0.0.1:8000/api/coins/LTC/", "to_coin": "http://127.0.0.1:8000/api/coins/SGTK/" } ]Example 2 (Filtering results):
GET /api/conversions/?from_coin=SGTK&to_coin=LTC HTTP 200 OK Content-Type: application/json [ { "url": "http://127.0.0.1:8000/api/conversions/6/", "from_address": "LKjpPtgMbcFgbJJYwzfe1ZtR8x4bbs2V3o", "to_address": "LKjpPtgMbcFgbJJYwzfe1ZtR8x4bbs2V3o", "to_memo": "Token Conversion from SGTK account privex", "to_amount": "0.00883200000000000000", "to_txid": "e4a5cb3ccc5524e20a39b1a076cef16a85efc68bf929e7a3ec4a834c30711e55", "tx_fee": "0.00016800000000000000", "ex_fee": "0.00100000000000000000", "created_at": "2019-03-21T10:14:20.021360Z", "updated_at": "2019-03-21T10:14:20.021373Z", "deposit": "http://127.0.0.1:8000/api/deposits/10/", "from_coin": "http://127.0.0.1:8000/api/coins/SGTK/", "to_coin": "http://127.0.0.1:8000/api/coins/LTC/" }, { "url": "http://127.0.0.1:8000/api/conversions/5/", "from_address": "LKjpPtgMbcFgbJJYwzfe1ZtR8x4bbs2V3o", "to_address": "LKjpPtgMbcFgbJJYwzfe1ZtR8x4bbs2V3o", "to_memo": "Token Conversion from SGTK account privex", "to_amount": "0.00433200000000000000", "to_txid": null, "tx_fee": "0.00016800000000000000", "ex_fee": "0.00050000000000000000", "created_at": "2019-03-20T04:56:53.859675Z", "updated_at": "2019-03-20T04:56:53.859691Z", "deposit": "http://127.0.0.1:8000/api/deposits/7/", "from_coin": "http://127.0.0.1:8000/api/coins/SGTK/", "to_coin": "http://127.0.0.1:8000/api/coins/LTC/" } ]Example 3 (ID Lookup):
GET /api/conversions/5/ HTTP 200 OK Content-Type: application/json { "url": "http://127.0.0.1:8000/api/conversions/5/", "from_address": "LKjpPtgMbcFgbJJYwzfe1ZtR8x4bbs2V3o", "to_address": "LKjpPtgMbcFgbJJYwzfe1ZtR8x4bbs2V3o", "to_memo": "Token Conversion from SGTK account privex", "to_amount": "0.00433200000000000000", "to_txid": null, "tx_fee": "0.00016800000000000000", "ex_fee": "0.00050000000000000000", "created_at": "2019-03-20T04:56:53.859675Z", "updated_at": "2019-03-20T04:56:53.859691Z", "deposit": "http://127.0.0.1:8000/api/deposits/7/", "from_coin": "http://127.0.0.1:8000/api/coins/SGTK/", "to_coin": "http://127.0.0.1:8000/api/coins/LTC/" }
/api/pairs/¶
/api/pairs/
- Returns all coin pairs supported by the system Can be filtered using the GET Parameters listed below.
/api/pairs/<id>
- Returns a single coin pair by it’s ID
Methods: GET
GET Parameters:
These parameters can be used with the plain /api/pairs/
URL, to filter coin pairs based on from/to symbol.
Note: Results from /api/pairs/
will always be returned as a list, even if there’s only one.
Parameter | Type | Description |
---|---|---|
to_coin | String | Return pairs with this destination coin symbol |
from_coin | String | Return pairs with this deposit coin symbol |
Example 1 (Plain GET request):
GET /api/pairs/
HTTP 200 OK
Content-Type: application/json
[
{
"id": 1,
"from_coin": "http://127.0.0.1:8000/api/coins/LTC/",
"from_coin_symbol": "LTC",
"to_coin": "http://127.0.0.1:8000/api/coins/SGTK/",
"to_coin_symbol": "SGTK",
"exchange_rate": "100000.00000000000000000000",
"__str__": "LTC -> SGTK (100000.0000 SGTK per LTC)"
},
{
"id": 2,
"from_coin": "http://127.0.0.1:8000/api/coins/SGTK/",
"from_coin_symbol": "SGTK",
"to_coin": "http://127.0.0.1:8000/api/coins/LTC/",
"to_coin_symbol": "LTC",
"exchange_rate": "0.01000000000000000000",
"__str__": "SGTK -> LTC (0.0100 LTC per SGTK)"
}
]
Example 2 (Filtering results):
GET /api/pairs/?from_coin=LTC
HTTP 200 OK
Content-Type: application/json
[
{
"id": 1,
"from_coin": "http://127.0.0.1:8000/api/coins/LTC/",
"from_coin_symbol": "LTC",
"to_coin": "http://127.0.0.1:8000/api/coins/SGTK/",
"to_coin_symbol": "SGTK",
"exchange_rate": "100000.00000000000000000000",
"__str__": "LTC -> SGTK (100000.0000 SGTK per LTC)"
}
]
Example 3 (ID Lookup):
GET /api/pairs/1/
HTTP 200 OK
Content-Type: application/json
{
"id": 1,
"from_coin": "http://127.0.0.1:8000/api/coins/LTC/",
"from_coin_symbol": "LTC",
"to_coin": "http://127.0.0.1:8000/api/coins/SGTK/",
"to_coin_symbol": "SGTK",
"exchange_rate": "100000.00000000000000000000",
"__str__": "LTC -> SGTK (100000.0000 SGTK per LTC)"
}