HodlHodl API Documentation (v1)
Notice: in order to use API you should enable it in your account preferences.
Authorization
Use API key from your account preferences and add the following header to each request:
Authorization: Bearer <your_api_key>
The next endpoints are public and do not require API key:
-
GET /api/v1/countries -
GET /api/v1/currencies -
GET /api/v1/offers -
GET /api/v1/offers/:id -
GET /api/v1/payment_methods
Error handling
The server will respond with JSON with error_code and relevant HTTP status.
The response is a JSON object (hash) with "status" key.
"status" is set to "success" (if the request was fulfilled) or
"error" (otherwise).
"error_code" key contains error code (short string) if "status" is "error".
If the requested entity wasn’t found, the following response
will be sent with 404 NOT FOUND HTTP status:
{
"status": "error",
"error_code": "not_found"
}
If required root parameter of the request is ommitted, the following response
will be sent with 400 BAD REQUEST HTTP status:
{
"status": "error",
"error_code": "missing_parameter",
"parameter": "<parameter name here>"
}
If service is temporarily unavailable, the following response will be sent with 503 SERVICE UNAVAILABLE HTTP status:
{
"status": "error",
"error_code": "not_available"
}
(When this reponse is received the request should be repeated later.)
Validation errors
If any validation errors occur when trying to create or update an entity, then the following response will be returned with HTTP status 422:
{
"status": "error",
"error": "validation",
"validation_errors": {
"<field>": ["<error1>", "<error2>", ...]
}
}
I.e., "validation_errors" will be returned, which is a hash. Each key of that hash corresponds to the entity’s erroneous field, and the value is an array of human-readable English strings (representing occured validation errors).
Contracts API restrictions
There is no way to create (resolve, work with, etc.) disputes or leave feedback to a counterparty via the API at the moment. Such actions currently should be performed manually via the website.
All contracts operations require payment password to be created via the website (Profile -> Trading Settings). This operation actually creates payment seed on the client (in the browser) and stores encrypted payment seed on the server. Payment seed should be created by offer’s acceptor as well as offer’s creator.
If payment password hasn’t been created on the website, validation error will be returned to “Create contract” request. Currently there is no way to create payment password/encrypted seed via the API for security reasons.
If “Bitcoin address” hasn’t been set in “Trading Settings”, validation error will be returned to “Create contract” request. Currently there is no way to set release address on a per contract basis for security reasons.
Encrypted payment seed could be retrieved via Users/Getting myself method.
Contracts API workflow
- Buyer or seller sends “Creating contract” request to the server
- Initiator sends “Getting contract” request once every 1-3 minutes until
contract.escrow.addressis notnull(thus, waiting for offer’s creator to confirm his payment password in case he uses the website) - Each party verifies the escrow address locally
- Each party sends “Confirming contract’s escrow validity” request to the server
- Seller deposits cryptocurrency to escrow address
- Buyer checks contract status with “Getting contract” request to the server once every 1-5 minutes until contract status is
"in_progress" - Buyer verifies locally that correct amount of cryptocurrency has been deposited to escrow address and correct number of blockchain confirmations has been received
- Buyer sends fiat payment to the seller
- Buyer sends “Marking contract as paid” request to the server
- Seller verifies locally that he actually has received fiat payment
- Seller fetches pre-signed by the server release transaction with “Showing release transaction of contract” request
- Seller verifies and signs the release transaction locally
- Seller sends the signed release transaction to the server with “Signing release transaction of contract”
If you are the seller, DO NOT SEND BITCOINS UNTIL CONTRACT STATUS IS "depositing".
If you are the buyer, DO NOT SEND PAYMENT UNTIL CONTRACT STATUS IS "in_progress".
Note: both buyer and seller could check contract status (including information on deposited cryptocurrency) at any time with “Getting contract” request.
For more detailed description of the process refer to HodlHodl Multisig contract specification.
Contracts SDK
For client-side multisig library and examples see hodl-client-js repository.