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

  1. Buyer or seller sends “Creating contract” request to the server
  2. Initiator sends “Getting contract” request once every 1-3 minutes until contract.escrow.address is not null (thus, waiting for offer’s creator to confirm his payment password in case he uses the website)
  3. Each party verifies the escrow address locally
  4. Each party sends “Confirming contract’s escrow validity” request to the server
  5. Seller deposits cryptocurrency to escrow address
  6. Buyer checks contract status with “Getting contract” request to the server once every 1-5 minutes until contract status is "in_progress"
  7. Buyer verifies locally that correct amount of cryptocurrency has been deposited to escrow address and correct number of blockchain confirmations has been received
  8. Buyer sends fiat payment to the seller
  9. Buyer sends “Marking contract as paid” request to the server
  10. Seller verifies locally that he actually has received fiat payment
  11. Seller fetches pre-signed by the server release transaction with “Showing release transaction of contract” request
  12. Seller verifies and signs the release transaction locally
  13. 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.

Chat messages

Chat messages resource

Listing chat messages for a contract

Endpoint

GET /api/v1/contracts/:contract_id/chat_messages

Parameters

Name Description
contract_id

Contract ID

Request

Route

GET /api/v1/contracts/sKoce3wyHIAeb8Yu/chat_messages

Headers

Authorization: Bearer aAb2qlDKQZsS4V1gPHT9.......
Content-Type: application/json

cURL

curl -g "hodlhodl.com/api/v1/contracts/sKoce3wyHIAeb8Yu/chat_messages" -X GET \
	-H "Authorization: Bearer aAb2qlDKQZsS4V1gPHT9......." \
	-H "Content-Type: application/json"

Response

Simulated Response

Response Fields

Name Description
chat_messages

Chat messages array

chat_messages[#].text

Text

chat_messages[#].author

Login of author

chat_messages[#].from_admin

Author is a trading platform’s admin? (true or false)

chat_messages[#].sent_at

Sent datetime in UTC, ISO8601 (YYYY-MM-DDThh:mm:ssZ)

Status

200

Headers

Content-Type: application/json; charset=utf-8

Body

{
  "status": "success",
  "chat_messages": [
    {
      "text": "Hi!",
      "author": "test_user",
      "from_admin": false,
      "sent_at": "2020-07-14T13:45:42Z"
    },
    {
      "text": "Hi to you!",
      "author": "us4r1",
      "from_admin": false,
      "sent_at": "2020-07-14T13:45:42Z"
    }
  ]
}

Contracts

Contracts resource

Getting contract

This method could be requested at any time by either party to check contract status (including status of cryptocurrency deposit).

Endpoint

GET /api/v1/contracts/:id

Parameters

Name Description
id

Contract ID

Request

Route

GET /api/v1/contracts/ypnTAScVMSrc1f59

Headers

Authorization: Bearer aAb2qlDKQZsS4V1gPHT9.......
Content-Type: application/json

cURL

curl -g "hodlhodl.com/api/v1/contracts/ypnTAScVMSrc1f59" -X GET \
	-H "Authorization: Bearer aAb2qlDKQZsS4V1gPHT9......." \
	-H "Content-Type: application/json"

Response

Simulated Response

Response Fields

Name Description
contract

Contract resource

contract.id

ID

contract.your_role

Your role ("buyer" or "seller")

contract.can_be_canceled

Can be canceled in its current state by you? (true or false)

contract.offer_id

Offer ID

contract.value

Value (i.e. fiat price of contract)

contract.price

Asset price (in currency_code fiat currency, at the moment of the creation of the contract)

contract.currency_code

Currency/asset code of “value” field (e.g. “USD”)

contract.volume

Volume (i.e. BTC price of contract)

contract.asset_code

Asset code of “volume” field (“BTC” or “BTCLN”)

contract.comment

Comment of the Contract’s initiator

contract.release_address

Release address (only shows in Getting contract method for buyer)

contract.confirmations

Blockchain confirmations required for deposit transaction in order for Contract to be considered "Deposited"

contract.payment_window_minutes

Payment window set by the offer author for the contract, during which the buyer must transfer the payment using the agreed upon payment method.

contract.depositing_window_minutes

Depositing window set by the exchange during which the seller must deposit bitcoins into escrow

contract.payment_window_time_left_seconds

Payment window time left (in seconds)

contract.payment_window_seconds_left

Payment window time left (in seconds, alias to payment_window_time_left_seconds, which is now deprecated)

contract.depositing_window_time_left_seconds

Depositing window time left (in seconds)

contract.country_code

Contract country code

contract.status

Contract status. There are the following statuses:

  • "pending" — awaiting confirmation from buyer and/or seller (initial status)
  • "depositing" — awaiting deposition from seller and confirmations from the blockchain
  • "in_progress" — deposition has been confirmed by the blockchain
  • "paid" — buyer has confirmed he’s sent the payment
  • "completed" — cryptocurrency has been released/transfered from the escrow (final status)
  • "canceled" — contract has been canceled (final status)
  • "disputed" — contract is disputed
  • "resolved" — dispute has been resolved by admin (final status; voluntary resolution instead leads to "completed" status)

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".

contract.dispute_status

Contract dispute status. null unless contract status is "resolved".

contract.country

Country name (or "Global")

contract.country_code

Country code (or "Global")

contract.created_at

Creation datetime in UTC, ISO8601 (YYYY-MM-DDThh:mm:ssZ)

contract.counterparty

Counterparty information

contract.counterparty.login

Login

contract.counterparty.online_status

"online", "recently_online" or "offline"

contract.counterparty.rating

Rating (as fraction of 1)

contract.counterparty.trades_count

Number of conducted trades

contract.counterparty.url

Hodlhodl website URL

contract.counterparty.verified

Verified? (true or false)

contract.counterparty.verified_by

Login of the Strong Hodler who verified this user

contract.counterparty.strong_hodler

Strong Hodler? (true or false)

Strong Hodler is a member of Hodl Hodl volunteer team that we’re working directly with.

contract.counterparty.country

Country name (or "Global")

contract.counterparty.country_code

Country code (or "Global")

contract.counterparty.average_payment_time_minutes

Average payment time (in minutes)

contract.counterparty.average_release_time_minutes

Average release time (in minutes)

contract.counterparty.days_since_last_trade

Number of days since last trade

contract.counterparty.blocked_by

How many traders blocked this user

Payment method instruction fields

contract.payment_method_instruction.payment_method_id

ID of payment method

contract.payment_method_instruction.details

Text of the instruction

Volume breakdown

contract.volume_breakdown.goes_to_buyer

Buyer receives this amount minus transaction fee

contract.volume_breakdown.exchange_fee

Amount of crypto currency that trading platform receives

contract.volume_breakdown.exchange_fee_in_fiat

Fiat equivalent of exchange fee (in currency_code currency)

contract.volume_breakdown.transaction_fee

Estimated blockchain transaction fee

Escrow information

contract.escrow.address

Escrow BTC address (for verification)

This field might be null if the offer’s creator uses the website and hasn’t yet confirmed one’s payment password. In such case, repeat this request once every 1-3 minutes until escrow address appears.

contract.escrow.witness_script

Escrow redeem witness script (for verification)

contract.escrow.index

Escrow xpub/xpriv index (for verification)

contract.escrow.you_confirmed

Have you verified and confirmed the escrow? (true or false)

contract.escrow.counterparty_confirmed

Have the other party verified and confirmed the escrow? (true or false)

contract.escrow.confirmations

Blockchain confirmations received so far

contract.escrow.amount_deposited

Amount deposited (in BTC; null when no deposit has been made yet)

contract.escrow.amount_released

Amount released (in BTC; null when no release has been made yet)

contract.escrow.deposit_transaction_id

Blockchain ID of deposit transaction (null when no deposit has been made yet)

contract.escrow.release_transaction_id

Blockchain ID of release transaction (null when no release has been made yet)

Status

200

Headers

Content-Type: application/json; charset=utf-8

Body

{
  "status": "success",
  "contract": {
    "id": "ypnTAScVMSrc1f59",
    "your_role": "seller",
    "can_be_canceled": true,
    "offer_id": "vOewSjIEMVmoyqGY",
    "price": "7000.00",
    "value": "7210.79",
    "currency_code": "EUR",
    "volume": "11.00000000",
    "asset_code": "BTC",
    "comment": "Sell me bitcoins, I agree to the terms!",
    "confirmations": 2,
    "payment_window_seconds_left": null,
    "payment_window_time_left_seconds": null,
    "payment_window_minutes": 60,
    "depositing_window_minutes": 30,
    "depositing_window_time_left_seconds": null,
    "status": "pending",
    "dispute_status": null,
    "payment_method_instruction": {
      "payment_method_id": "4430",
      "details": "Wire transfer to account #123123"
    },
    "volume_breakdown": {
      "goes_to_buyer": "10.78000000",
      "exchange_fee": "0.22000000",
      "exchange_fee_in_fiat": "770.00",
      "transaction_fee": "0.00003291"
    },
    "country": "Country 14",
    "country_code": "Country Code 14",
    "created_at": "2020-07-14T13:45:42Z",
    "counterparty": {
      "login": "us4r2",
      "avatar_url": "http://example.org/assets/default_avatar-f5b0258802df64cd87d94b95a1faed32b1b464bfb9b1cef2a10f6c30ddc91158.svg",
      "online_status": "offline",
      "rating": null,
      "trades_count": 0,
      "url": "http://hodldev.local:3001/accounts/us4r2",
      "verified": false,
      "verified_by": null,
      "strong_hodler": false,
      "country": "Country 15",
      "country_code": "Country Code 15",
      "average_payment_time_minutes": null,
      "average_release_time_minutes": null,
      "days_since_last_trade": null,
      "blocked_by": 0
    },
    "escrow": {
      "address": null,
      "witness_script": null,
      "index": null,
      "you_confirmed": false,
      "counterparty_confirmed": false,
      "confirmations": 0,
      "amount_deposited": null,
      "amount_released": null,
      "deposit_transaction_id": null,
      "release_transaction_id": null
    }
  }
}

Listing my contracts

This method will return all your existing contracts, recently created first.

Response could be filtered by side and/or by status.

Endpoint

GET /api/v1/contracts/my

Parameters

Name Description
pagination.limit

Number of records to return (default 50, maximum 100)

pagination.offset

Number of records to skip (e.g. 50 for second page of results with the default limit)

filters.side

"buy" or "sell"

filters.status

Status, see contract.status response field in Getting contract

Request

Route

GET /api/v1/contracts/my?filters[status]=pending

Headers

Authorization: Bearer aAb2qlDKQZsS4V1gPHT9.......
Content-Type: application/json

Query Parameters as JSON

{
  "filters": {
    "status": "pending"
  }
}

cURL

curl -g "hodlhodl.com/api/v1/contracts/my?filters[status]=pending" -X GET \
	-H "Authorization: Bearer aAb2qlDKQZsS4V1gPHT9......." \
	-H "Content-Type: application/json"

Response

Simulated Response

Response Fields

Name Description
contracts

Array of Contracts (see Getting contract for fields description)

Status

200

Headers

Content-Type: application/json; charset=utf-8

Body

{
  "status": "success",
  "filters": {
    "status": "pending"
  },
  "pagination": {
    "limit": 50,
    "offset": 0
  },
  "contracts": [
    {
      "id": "bT883OiqJ8NJHfUh",
      "your_role": "buyer",
      "can_be_canceled": true,
      "offer_id": "q2hLtGKiKoWyy9b4",
      "price": "725.53",
      "value": "7900.98",
      "currency_code": "USD",
      "volume": "11.00000000",
      "asset_code": "BTC",
      "comment": "Sell me bitcoins, I agree to the terms!",
      "release_address": "n45ssNV2o1ursURPhLvF1AXVtzrcvKrpPZ",
      "confirmations": 1,
      "payment_window_seconds_left": null,
      "payment_window_time_left_seconds": null,
      "payment_window_minutes": 60,
      "depositing_window_minutes": 30,
      "depositing_window_time_left_seconds": null,
      "status": "pending",
      "dispute_status": null,
      "payment_method_instruction": {
        "payment_method_id": "4433",
        "details": "Send money over to account 123"
      },
      "volume_breakdown": {
        "goes_to_buyer": "10.78000000",
        "exchange_fee": "0.22000000",
        "exchange_fee_in_fiat": "79.81",
        "transaction_fee": "0.00003291"
      },
      "country": "Country 27",
      "country_code": "Country Code 27",
      "created_at": "2020-07-13T13:45:43Z",
      "counterparty": {
        "login": "us4r3",
        "avatar_url": "http://example.org/assets/default_avatar-f5b0258802df64cd87d94b95a1faed32b1b464bfb9b1cef2a10f6c30ddc91158.svg",
        "online_status": "offline",
        "rating": null,
        "trades_count": 0,
        "url": "http://hodldev.local:3001/accounts/us4r3",
        "verified": false,
        "verified_by": null,
        "strong_hodler": false,
        "country": "Country 23",
        "country_code": "Country Code 23",
        "average_payment_time_minutes": null,
        "average_release_time_minutes": null,
        "days_since_last_trade": null,
        "blocked_by": 0
      },
      "escrow": {
        "address": "2NEESxWFsM4MgwrbSqwjMSBqW8KZ3FPxTFW",
        "witness_script": "522103f00bf3d196d4a858b0764bb1416773732dddc1f973ae425cb1a114452462296f2103b238226016a53822063b4a2ddaee55e2ffe379afb8c252fdfffa29aa7c6b40902103b238226016a53822063b4a2ddaee55e2ffe379afb8c252fdfffa29aa7c6b409053ae",
        "index": 214,
        "you_confirmed": false,
        "counterparty_confirmed": false,
        "confirmations": 0,
        "amount_deposited": "0.00000000",
        "amount_released": null,
        "deposit_transaction_id": null,
        "release_transaction_id": null
      }
    },
    {
      "id": "rLY1LfuCe0Ru7Jnf",
      "your_role": "seller",
      "can_be_canceled": true,
      "offer_id": "Qw6E5piI6RQYeuRf",
      "price": "725.53",
      "value": "7900.98",
      "currency_code": "USD",
      "volume": "11.00000000",
      "asset_code": "BTC",
      "comment": "Sell me bitcoins, I agree to the terms!",
      "confirmations": 1,
      "payment_window_seconds_left": null,
      "payment_window_time_left_seconds": null,
      "payment_window_minutes": 60,
      "depositing_window_minutes": 30,
      "depositing_window_time_left_seconds": null,
      "status": "pending",
      "dispute_status": null,
      "payment_method_instruction": {
        "payment_method_id": "4435",
        "details": "Send money over to account 123"
      },
      "volume_breakdown": {
        "goes_to_buyer": "10.78000000",
        "exchange_fee": "0.22000000",
        "exchange_fee_in_fiat": "79.81",
        "transaction_fee": "0.00003291"
      },
      "country": "Country 40",
      "country_code": "Country Code 40",
      "created_at": "2020-07-12T13:45:43Z",
      "counterparty": {
        "login": "us4r6",
        "avatar_url": "http://example.org/assets/default_avatar-f5b0258802df64cd87d94b95a1faed32b1b464bfb9b1cef2a10f6c30ddc91158.svg",
        "online_status": "offline",
        "rating": null,
        "trades_count": 0,
        "url": "http://hodldev.local:3001/accounts/us4r6",
        "verified": false,
        "verified_by": null,
        "strong_hodler": false,
        "country": "Country 36",
        "country_code": "Country Code 36",
        "average_payment_time_minutes": null,
        "average_release_time_minutes": null,
        "days_since_last_trade": null,
        "blocked_by": 0
      },
      "escrow": {
        "address": "2NGVpCG3MbpPPfwEqTErh45fyaDA9gz1YbW",
        "witness_script": "522103e99f7b45ef36f200cd7b98defc1061340635ec9f8229c69b09206ed4cc3bbaa4210239bebc13bd2e43fea6e0cd2899068a4954f1d398eccdeb7b74b63572b9a59cbf210239bebc13bd2e43fea6e0cd2899068a4954f1d398eccdeb7b74b63572b9a59cbf53ae",
        "index": 215,
        "you_confirmed": false,
        "counterparty_confirmed": false,
        "confirmations": 0,
        "amount_deposited": "0.00000000",
        "amount_released": null,
        "deposit_transaction_id": null,
        "release_transaction_id": null
      }
    },
    {
      "id": "rG2KUqOB0qiiZxuv",
      "your_role": "buyer",
      "can_be_canceled": true,
      "offer_id": "q2hLtGKiKoWyy9b4",
      "price": "725.53",
      "value": "7900.98",
      "currency_code": "USD",
      "volume": "11.00000000",
      "asset_code": "BTC",
      "comment": "Sell me bitcoins, I agree to the terms!",
      "release_address": "n45ssNV2o1ursURPhLvF1AXVtzrcvKrpPZ",
      "confirmations": 1,
      "payment_window_seconds_left": null,
      "payment_window_time_left_seconds": null,
      "payment_window_minutes": 60,
      "depositing_window_minutes": 30,
      "depositing_window_time_left_seconds": null,
      "status": "pending",
      "dispute_status": null,
      "payment_method_instruction": {
        "payment_method_id": "4432",
        "details": "Send money over to account 123"
      },
      "volume_breakdown": {
        "goes_to_buyer": "10.78000000",
        "exchange_fee": "0.22000000",
        "exchange_fee_in_fiat": "79.81",
        "transaction_fee": "0.00003291"
      },
      "country": "Country 27",
      "country_code": "Country Code 27",
      "created_at": "2020-07-09T13:45:43Z",
      "counterparty": {
        "login": "us4r3",
        "avatar_url": "http://example.org/assets/default_avatar-f5b0258802df64cd87d94b95a1faed32b1b464bfb9b1cef2a10f6c30ddc91158.svg",
        "online_status": "offline",
        "rating": null,
        "trades_count": 0,
        "url": "http://hodldev.local:3001/accounts/us4r3",
        "verified": false,
        "verified_by": null,
        "strong_hodler": false,
        "country": "Country 23",
        "country_code": "Country Code 23",
        "average_payment_time_minutes": null,
        "average_release_time_minutes": null,
        "days_since_last_trade": null,
        "blocked_by": 0
      },
      "escrow": {
        "address": "2N9HUJyuQjZVQXW3iK56zC8cz6Vv19LmSAC",
        "witness_script": "5221038d9d7caf844a86a904fa98dcdcd26b217e49cd17e7fb9ff61f6f039d44ecaa81210397385b02a2a0662be23bc66186d488caba3898393ce635a48d6abbd7886a4a53210397385b02a2a0662be23bc66186d488caba3898393ce635a48d6abbd7886a4a5353ae",
        "index": 213,
        "you_confirmed": false,
        "counterparty_confirmed": false,
        "confirmations": 0,
        "amount_deposited": "0.00000000",
        "amount_released": null,
        "deposit_transaction_id": null,
        "release_transaction_id": null
      }
    }
  ]
}

Creating contract

Note 1. offer_version and payment_method_instruction_version could be obtained by querying Getting offer. Clients should not interpret this value. This value will change every time the corresponding offer or payment method instruction is changed. Requiring to provide these values on contract creation ensures that the end-user agrees to the exact terms of offer which he has seen.

Note 2. To create contract for “buy” offer, payment_method_instruction_id should be ID of one of your payment method instructions (see Payment method instructions resource). payment_method_id of the given payment method instruction should be one of the payment_method_ids of the offer.

To create contract for “sell” offer, payment_method_instruction_id should be ID of one of the offer’s payment_method_instructions.id (see Getting offer).

Note 3. Either value or volume must be present in the request (but not both). Non-present value will be calculated automatically (using offer’s price of the created contract).

Note 4. When volume is provided by buyer, actual contract volume is increased to account for trading platform’s fee.

Endpoint

POST /api/v1/contracts

Parameters

Name Description
contract.offer_id

Offer ID (required)

contract.offer_version

Offer version 1 (required)

contract.payment_method_instruction_id

Payment method instruction ID (required) 2

contract.payment_method_instruction_version

Payment method instruction version 1 (required)

contract.comment

Comment of the Contract’s initiator

Value/volume fields 3 (exactly 1 of the following is required):

contract.value

Value (i.e. fiat price of contract; will be rounded to 2 decimal digits)

contract.volume

Volume (i.e. BTC price of contract) 4

Request

Route

POST /api/v1/contracts

Headers

Authorization: Bearer aAb2qlDKQZsS4V1gPHT9.......
Content-Type: application/json

Body

{
  "contract": {
    "offer_id": "9QTmnkDTE2g1abyL",
    "offer_version": "219ed5hb",
    "payment_method_instruction_id": 4576,
    "payment_method_instruction_version": "219ed5h9",
    "comment": "I accept your offer",
    "value": 3500
  }
}

cURL

curl "hodlhodl.com/api/v1/contracts" -d '{"contract":{"offer_id":"9QTmnkDTE2g1abyL","offer_version":"219ed5hb","payment_method_instruction_id":4576,"payment_method_instruction_version":"219ed5h9","comment":"I accept your offer","value":3500}}' -X POST \
	-H "Authorization: Bearer aAb2qlDKQZsS4V1gPHT9......." \
	-H "Content-Type: application/json"

Response

Simulated Response

Response Fields

Name Description
contract

Contract (see Getting contract for fields description)

Status

200

Headers

Content-Type: application/json; charset=utf-8

Body

{
  "status": "success",
  "contract": {
    "id": "anPNzumIsstYKWlx",
    "your_role": "buyer",
    "can_be_canceled": true,
    "offer_id": "9QTmnkDTE2g1abyL",
    "price": "7000.00",
    "value": "3500.00",
    "currency_code": "EUR",
    "volume": "0.50500000",
    "asset_code": "BTC",
    "comment": "I accept your offer",
    "release_address": "n45ssNV2o1ursURPhLvF1AXVtzrcvKrpPZ",
    "confirmations": 2,
    "payment_window_seconds_left": null,
    "payment_window_time_left_seconds": null,
    "payment_window_minutes": 60,
    "depositing_window_minutes": 30,
    "depositing_window_time_left_seconds": null,
    "status": "pending",
    "dispute_status": null,
    "payment_method_instruction": {
      "payment_method_id": "4436",
      "details": "Wire transfer to account #123123"
    },
    "volume_breakdown": {
      "goes_to_buyer": "0.49490000",
      "exchange_fee": "0.01010000",
      "exchange_fee_in_fiat": "35.35",
      "transaction_fee": "0.00003291"
    },
    "country": "Country 53",
    "country_code": "Country Code 53",
    "created_at": "2020-07-14T13:45:43Z",
    "counterparty": {
      "login": "us4r8",
      "avatar_url": "http://example.org/assets/default_avatar-f5b0258802df64cd87d94b95a1faed32b1b464bfb9b1cef2a10f6c30ddc91158.svg",
      "online_status": "offline",
      "rating": null,
      "trades_count": 0,
      "url": "http://hodldev.local:3001/accounts/us4r8",
      "verified": false,
      "verified_by": null,
      "strong_hodler": false,
      "country": "Country 49",
      "country_code": "Country Code 49",
      "average_payment_time_minutes": null,
      "average_release_time_minutes": null,
      "days_since_last_trade": null,
      "blocked_by": 0
    },
    "escrow": {
      "address": "2N9grbF4cX5gaZkYjD8XSahWrqFyJ2Tee3J",
      "witness_script": "5221031879437c6e36abb3848ee7e9a4a1e87b8bb7747f4c9b449e6dac28431e89cef42103d5bb2f3c369c54746885d18852a7ca8e2c769a5419e8489b1c37db8013d0ff152103d5bb2f3c369c54746885d18852a7ca8e2c769a5419e8489b1c37db8013d0ff1553ae",
      "index": 216,
      "you_confirmed": false,
      "counterparty_confirmed": false,
      "confirmations": 0,
      "amount_deposited": "0.00000000",
      "amount_released": null,
      "deposit_transaction_id": null,
      "release_transaction_id": null
    }
  }
}

Confirming contract's escrow validity

This method is used to confirm that client-side validation of escrow data was successful.

This method should be called immediately after escrow address appeared in Getting contract response and this escrow address has been verified locally by the client.

Client should verify contract’s escrow data (witness script, address and index) and then send this request. See JS client documentation/examples for more details.

This method gives information to the server that the calling party agrees to go forward with the contract. Clients should ensure by themselves independently that they move funds to the correct address/escrow.

Endpoint

POST /api/v1/contracts/:id/confirm

Parameters

Name Description
id

Contract ID

Request

Route

POST /api/v1/contracts/smZwD50WTCPS8Vim/confirm

Headers

Authorization: Bearer aAb2qlDKQZsS4V1gPHT9.......
Content-Type: application/json

cURL

curl "hodlhodl.com/api/v1/contracts/smZwD50WTCPS8Vim/confirm" -d '' -X POST \
	-H "Authorization: Bearer aAb2qlDKQZsS4V1gPHT9......." \
	-H "Content-Type: application/json"

Response

Simulated Response

Response Fields

Name Description
contract

Contract (see Getting contract for fields description)

Status

200

Headers

Content-Type: application/json; charset=utf-8

Body

{
  "status": "success",
  "contract": {
    "id": "smZwD50WTCPS8Vim",
    "your_role": "buyer",
    "can_be_canceled": true,
    "offer_id": "HogKOcKpsSXK8nKa",
    "price": "7000.00",
    "value": "7210.79",
    "currency_code": "EUR",
    "volume": "11.00000000",
    "asset_code": "BTC",
    "comment": "Sell me bitcoins, I agree to the terms!",
    "release_address": "n45ssNV2o1ursURPhLvF1AXVtzrcvKrpPZ",
    "confirmations": 2,
    "payment_window_seconds_left": null,
    "payment_window_time_left_seconds": null,
    "payment_window_minutes": 60,
    "depositing_window_minutes": 30,
    "depositing_window_time_left_seconds": null,
    "status": "pending",
    "dispute_status": null,
    "payment_method_instruction": {
      "payment_method_id": "4437",
      "details": "Wire transfer to account #123123"
    },
    "volume_breakdown": {
      "goes_to_buyer": "10.78000000",
      "exchange_fee": "0.22000000",
      "exchange_fee_in_fiat": "770.00",
      "transaction_fee": "0.00003291"
    },
    "country": "Country 62",
    "country_code": "Country Code 62",
    "created_at": "2020-07-14T13:45:43Z",
    "counterparty": {
      "login": "us4r9",
      "avatar_url": "http://example.org/assets/default_avatar-f5b0258802df64cd87d94b95a1faed32b1b464bfb9b1cef2a10f6c30ddc91158.svg",
      "online_status": "offline",
      "rating": null,
      "trades_count": 0,
      "url": "http://hodldev.local:3001/accounts/us4r9",
      "verified": false,
      "verified_by": null,
      "strong_hodler": false,
      "country": "Country 58",
      "country_code": "Country Code 58",
      "average_payment_time_minutes": null,
      "average_release_time_minutes": null,
      "days_since_last_trade": null,
      "blocked_by": 0
    },
    "escrow": {
      "address": "2Myv7YWTbU4xNNL7LiJ3AubbEPgssTpBATC",
      "witness_script": "52210342709b3ba6e7799b87e70024965590cca77beb3d069e382fded83994e417a75b2102c280f140eb28a27f1428493f262ada9a115e9846a938c8eaa807b65e30d61f5e2102c280f140eb28a27f1428493f262ada9a115e9846a938c8eaa807b65e30d61f5e53ae",
      "index": 217,
      "you_confirmed": true,
      "counterparty_confirmed": false,
      "confirmations": 0,
      "amount_deposited": "0.00000000",
      "amount_released": null,
      "deposit_transaction_id": null,
      "release_transaction_id": null
    }
  }
}

Marking contract as paid

Buyer (and only buyer) should call this method when fiat payment was made.

This method could be called only if contract’s status is "in_progress".

Endpoint

POST /api/v1/contracts/:id/mark_as_paid

Parameters

Name Description
id

Contract ID

Request

Route

POST /api/v1/contracts/7dvGC4G9WbLWD4wm/mark_as_paid

Headers

Authorization: Bearer aAb2qlDKQZsS4V1gPHT9.......
Content-Type: application/json

cURL

curl "hodlhodl.com/api/v1/contracts/7dvGC4G9WbLWD4wm/mark_as_paid" -d '' -X POST \
	-H "Authorization: Bearer aAb2qlDKQZsS4V1gPHT9......." \
	-H "Content-Type: application/json"

Response

Simulated Response

Response Fields

Name Description
contract

Contract (see Getting contract for fields description)

Status

200

Headers

Content-Type: application/json; charset=utf-8

Body

{
  "status": "success",
  "contract": {
    "id": "7dvGC4G9WbLWD4wm",
    "your_role": "buyer",
    "can_be_canceled": false,
    "offer_id": "7EbO4cwNqNLWfbp9",
    "price": "7000.00",
    "value": "7210.79",
    "currency_code": "EUR",
    "volume": "11.00000000",
    "asset_code": "BTC",
    "comment": "Sell me bitcoins, I agree to the terms!",
    "release_address": "n45ssNV2o1ursURPhLvF1AXVtzrcvKrpPZ",
    "confirmations": 2,
    "payment_window_seconds_left": 3599862000,
    "payment_window_time_left_seconds": 3599862000,
    "payment_window_minutes": 60,
    "depositing_window_minutes": 30,
    "depositing_window_time_left_seconds": null,
    "status": "paid",
    "dispute_status": null,
    "payment_method_instruction": {
      "payment_method_id": "4438",
      "details": "Wire transfer to account #123123"
    },
    "volume_breakdown": {
      "goes_to_buyer": "10.78000000",
      "exchange_fee": "0.22000000",
      "exchange_fee_in_fiat": "770.00",
      "transaction_fee": "0.00003291"
    },
    "country": "Country 71",
    "country_code": "Country Code 71",
    "created_at": "2020-07-14T13:45:44Z",
    "counterparty": {
      "login": "us4r10",
      "avatar_url": "http://example.org/assets/default_avatar-f5b0258802df64cd87d94b95a1faed32b1b464bfb9b1cef2a10f6c30ddc91158.svg",
      "online_status": "offline",
      "rating": null,
      "trades_count": 0,
      "url": "http://hodldev.local:3001/accounts/us4r10",
      "verified": false,
      "verified_by": null,
      "strong_hodler": false,
      "country": "Country 67",
      "country_code": "Country Code 67",
      "average_payment_time_minutes": null,
      "average_release_time_minutes": null,
      "days_since_last_trade": null,
      "blocked_by": 0
    },
    "escrow": {
      "address": "2MtSepJrQ2tgSeqgPGYmaKr1e9FgNJJ6dfA",
      "witness_script": "5221030f2c72268ee08a4e14d5f2f71edadbb08e8e82f428759946aef394c82842e801210309c5369e29bd2237e6cc8c18c95e44ae2bdf6ba2e04a719b688e7d0221e02626210309c5369e29bd2237e6cc8c18c95e44ae2bdf6ba2e04a719b688e7d0221e0262653ae",
      "index": 218,
      "you_confirmed": true,
      "counterparty_confirmed": true,
      "confirmations": 0,
      "amount_deposited": "11.00000000",
      "amount_released": null,
      "deposit_transaction_id": null,
      "release_transaction_id": null
    }
  }
}

Canceling contract

Contract could be canceled when any of the following conditions are met:

  • Contract status is "pending" and there are no bitcoins at the escrow address according to our most recent data
  • Contract status is "depositing" and you are the seller
  • Contract status is "depositing", you are the buyer, and depositing time has expired
  • Contract status is "in_progress" and you are the buyer
  • Contract status is "in_progress", you are the seller, and payment window has expired

If none of the conditions above are met then a validation error will be returned:

{
  "status": "error",
  "error_code": "validation",
  "validation_errors": {
    "id": ["Contract in its current state can't be cancelled by you"]
  }
}

Endpoint

POST /api/v1/contracts/:id/cancel

Parameters

Name Description
id

Contract ID

Request

Route

POST /api/v1/contracts/hUSReZTf1OtE99gC/cancel

Headers

Authorization: Bearer aAb2qlDKQZsS4V1gPHT9.......
Content-Type: application/json

cURL

curl "hodlhodl.com/api/v1/contracts/hUSReZTf1OtE99gC/cancel" -d '' -X POST \
	-H "Authorization: Bearer aAb2qlDKQZsS4V1gPHT9......." \
	-H "Content-Type: application/json"

Response

Simulated Response

Response Fields

Name Description
contract

Contract (see Getting contract for fields description)

Status

200

Headers

Content-Type: application/json; charset=utf-8

Body

{
  "status": "success",
  "contract": {
    "id": "hUSReZTf1OtE99gC",
    "your_role": "buyer",
    "can_be_canceled": false,
    "offer_id": "4SSKQUnDueXcMxBX",
    "price": "7000.00",
    "value": "7210.79",
    "currency_code": "EUR",
    "volume": "11.00000000",
    "asset_code": "BTC",
    "comment": "Sell me bitcoins, I agree to the terms!",
    "release_address": "n45ssNV2o1ursURPhLvF1AXVtzrcvKrpPZ",
    "confirmations": 2,
    "payment_window_seconds_left": null,
    "payment_window_time_left_seconds": null,
    "payment_window_minutes": 60,
    "depositing_window_minutes": 30,
    "depositing_window_time_left_seconds": null,
    "status": "canceled",
    "dispute_status": null,
    "payment_method_instruction": {
      "payment_method_id": "4439",
      "details": "Wire transfer to account #123123"
    },
    "volume_breakdown": {
      "goes_to_buyer": "10.78000000",
      "exchange_fee": "0.22000000",
      "exchange_fee_in_fiat": "770.00",
      "transaction_fee": "0.00003291"
    },
    "country": "Country 80",
    "country_code": "Country Code 80",
    "created_at": "2020-07-14T13:45:44Z",
    "counterparty": {
      "login": "us4r11",
      "avatar_url": "http://example.org/assets/default_avatar-f5b0258802df64cd87d94b95a1faed32b1b464bfb9b1cef2a10f6c30ddc91158.svg",
      "online_status": "offline",
      "rating": null,
      "trades_count": 0,
      "url": "http://hodldev.local:3001/accounts/us4r11",
      "verified": false,
      "verified_by": null,
      "strong_hodler": false,
      "country": "Country 76",
      "country_code": "Country Code 76",
      "average_payment_time_minutes": null,
      "average_release_time_minutes": null,
      "days_since_last_trade": null,
      "blocked_by": 0
    },
    "escrow": {
      "address": null,
      "witness_script": null,
      "index": null,
      "you_confirmed": false,
      "counterparty_confirmed": false,
      "confirmations": 0,
      "amount_deposited": null,
      "amount_released": null,
      "deposit_transaction_id": null,
      "release_transaction_id": null
    }
  }
}

Showing release transaction of contract

This method should be called by seller when contract status is "paid"; or bu buyer when contract status is "resolved" and "dispute_status" is "resolved_in_favor_of_buyer".

Endpoint

GET /api/v1/contracts/:id/release_transaction

Parameters

Name Description
id

Contract ID

Request

Route

GET /api/v1/contracts/r7or3lOu01ue9CWq/release_transaction

Headers

Authorization: Bearer aAb2qlDKQZsS4V1gPHT9.......
Content-Type: application/json

cURL

curl -g "hodlhodl.com/api/v1/contracts/r7or3lOu01ue9CWq/release_transaction" -X GET \
	-H "Authorization: Bearer aAb2qlDKQZsS4V1gPHT9......." \
	-H "Content-Type: application/json"

Response

Simulated Response

Response Fields

Name Description
transaction.contract_id

Contract ID

transaction.hex

Hex string which represents transaction to be signed

transaction.in_amounts

tx_in amounts of the transaction (Array of Integers)

Status

200

Headers

Content-Type: application/json; charset=utf-8

Body

{
  "status": "success",
  "transaction": {
    "contract_id": "r7or3lOu01ue9CWq",
    "hex": "01000000000101931f8e609e3e5a15d6c4965f5cbbb29c32a6f2e9e49e5f0194fc41cf8fdd441c0000000023220020d1aaab5a51e3526059374da5bc01ab2a9afd6c7fc7725f54c6d2cee0225b9c15ffffffff0239f14040000000001976a914f78cccb98956d9412ec023e18329d98e134c3fa888ac80b14f01000000001600149a4930b4ce7289c899053fa4a6d11a37ef4c919a0400473044022046800876ca3cdaa25b0ae60c7d06a572088dc240cc715be326614028d364c8ba022076f4b2ab28bed92e82c3d33e192688db91b47cf758fba62f77266b9906f86fe10146000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000006952210348cc64b0f682d77577a43cb7caa7fa802c99c50f8aadd9b9c9e5e516e57b8a5421020e4556c471a41626d15b01ddcfca8784edcdd6d55c888ebb909d3fc2bf780ac521020e4556c471a41626d15b01ddcfca8784edcdd6d55c888ebb909d3fc2bf780ac553ae00000000",
    "in_amounts": [
      1100000000
    ]
  }
}

Showing refund transaction of contract

This method should be called by seller when contract status is "resolved" and "dispute_status" is "resolved_in_favor_of_seller".

Endpoint

GET /api/v1/contracts/:id/refund_transaction

Parameters

Name Description
id

Contract ID

release_address

Release address for the refund (required)

Request

Route

GET /api/v1/contracts/0M4fL1lBydK6tkFw/refund_transaction?release_address=n4VQ5YdHf7hLQ2gWQYYrcxoE5B7nWuDFNF

Headers

Authorization: Bearer aAb2qlDKQZsS4V1gPHT9.......
Content-Type: application/json

Query Parameters as JSON

{
  "release_address": "n4VQ5YdHf7hLQ2gWQYYrcxoE5B7nWuDFNF"
}

cURL

curl -g "hodlhodl.com/api/v1/contracts/0M4fL1lBydK6tkFw/refund_transaction?release_address=n4VQ5YdHf7hLQ2gWQYYrcxoE5B7nWuDFNF" -X GET \
	-H "Authorization: Bearer aAb2qlDKQZsS4V1gPHT9......." \
	-H "Content-Type: application/json"

Response

Simulated Response

Response Fields

Name Description
transaction.contract_id

Contract ID

transaction.hex

Hex string which represents transaction to be signed

transaction.in_amounts

tx_in amounts of the transaction (Array of Integers)

Status

200

Headers

Content-Type: application/json; charset=utf-8

Body

{
  "status": "success",
  "transaction": {
    "contract_id": "0M4fL1lBydK6tkFw",
    "hex": "01000000000101931f8e609e3e5a15d6c4965f5cbbb29c32a6f2e9e49e5f0194fc41cf8fdd441c0000000023220020eb17e592575e983fdffd887c7a2cf2e63f9cf577bb3c1b9fd2ff8106efa9224dffffffff01e8a39041000000001976a914fbff95b4e35aca918d26e157392ea1643a2dc28388ac0400473044022043503a63ea7e9f679958ee87f076482f150f01e245c924b1ec01639de73467520220342800c00104ae6f573d028e66ea5f1d7605bfa08229a25d9021251702f1738301460000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000069522102af77e46010821a3d47ad956cd3d14b6c5f4434f1811c8106df977cf15eb9b5e0210368518ebac9d0fd122b8afe68f7950b9db7563b27e517ad4fe4896903d249fff6210368518ebac9d0fd122b8afe68f7950b9db7563b27e517ad4fe4896903d249fff653ae00000000",
    "in_amounts": [
      1100000000
    ]
  }
}

Signing release transaction of contract

This method seller should call after viewing & verifying release transaction. Provide signed transaction as hex string in the "hex" parameter.

Endpoint

POST /api/v1/contracts/:id/release_transaction

Parameters

Name Description
id

Contract ID

hex

Hex string which represents signed transaction

Request

Route

POST /api/v1/contracts/i10zKvZLCVGVUnMM/release_transaction

Headers

Authorization: Bearer aAb2qlDKQZsS4V1gPHT9.......
Content-Type: application/json

Body

{
  "hex": "123..."
}

cURL

curl "hodlhodl.com/api/v1/contracts/i10zKvZLCVGVUnMM/release_transaction" -d '{"hex":"123..."}' -X POST \
	-H "Authorization: Bearer aAb2qlDKQZsS4V1gPHT9......." \
	-H "Content-Type: application/json"

Response

Simulated Response

Response Fields

Name Description
contract

Contract (see Getting contract for fields description)

Status

200

Headers

Content-Type: application/json; charset=utf-8

Body

{
  "status": "success",
  "contract": {
    "id": "i10zKvZLCVGVUnMM",
    "your_role": "seller",
    "can_be_canceled": false,
    "offer_id": "jcJE2YDDJmjVbeko",
    "price": "7000.00",
    "value": "7210.79",
    "currency_code": "EUR",
    "volume": "11.00000000",
    "asset_code": "BTC",
    "comment": "Sell me bitcoins, I agree to the terms!",
    "confirmations": 2,
    "payment_window_seconds_left": 3599548000,
    "payment_window_time_left_seconds": 3599548000,
    "payment_window_minutes": 60,
    "depositing_window_minutes": 30,
    "depositing_window_time_left_seconds": null,
    "status": "completed",
    "dispute_status": null,
    "payment_method_instruction": {
      "payment_method_id": "4444",
      "details": "Wire transfer to account #123123"
    },
    "volume_breakdown": {
      "goes_to_buyer": "10.78000000",
      "exchange_fee": "0.22000000",
      "exchange_fee_in_fiat": "770.00",
      "transaction_fee": "0.00003291"
    },
    "country": "Country 107",
    "country_code": "Country Code 107",
    "created_at": "2020-07-14T13:45:45Z",
    "counterparty": {
      "login": "us4r14",
      "avatar_url": "http://example.org/assets/default_avatar-f5b0258802df64cd87d94b95a1faed32b1b464bfb9b1cef2a10f6c30ddc91158.svg",
      "online_status": "offline",
      "rating": null,
      "trades_count": 1,
      "url": "http://hodldev.local:3001/accounts/us4r14",
      "verified": false,
      "verified_by": null,
      "strong_hodler": false,
      "country": "Country 103",
      "country_code": "Country Code 103",
      "average_payment_time_minutes": 0,
      "average_release_time_minutes": null,
      "days_since_last_trade": 0,
      "blocked_by": 0
    },
    "escrow": {
      "address": "2N2Qp2JU9d3wHwYr9meueYMTPeqMqtfRBEa",
      "witness_script": "522103cf258982eb83c0077a5d6d4150802a9abd0cecc9a0559ff749e92614d7794d4a2103a3b21da4590331f27853fb5d453b6e104571a47ee34a5dd20def26dbad8c0d3f2103a3b21da4590331f27853fb5d453b6e104571a47ee34a5dd20def26dbad8c0d3f53ae",
      "index": 221,
      "you_confirmed": true,
      "counterparty_confirmed": true,
      "confirmations": 0,
      "amount_deposited": "11.00000000",
      "amount_released": null,
      "deposit_transaction_id": null,
      "release_transaction_id": null
    }
  }
}

Signing refund transaction of contract

This method seller should call after viewing & verifying refund transaction. Provide signed transaction as hex string in the "hex" parameter.

Endpoint

POST /api/v1/contracts/:id/refund_transaction

Parameters

Name Description
id

Contract ID

hex

Hex string which represents signed transaction

Request

Route

POST /api/v1/contracts/oYG9dyXNwAD8k7LZ/refund_transaction

Headers

Authorization: Bearer aAb2qlDKQZsS4V1gPHT9.......
Content-Type: application/json

Body

{
  "hex": "123..."
}

cURL

curl "hodlhodl.com/api/v1/contracts/oYG9dyXNwAD8k7LZ/refund_transaction" -d '{"hex":"123..."}' -X POST \
	-H "Authorization: Bearer aAb2qlDKQZsS4V1gPHT9......." \
	-H "Content-Type: application/json"

Response

Simulated Response

Response Fields

Name Description
contract

Contract (see Getting contract for fields description)

Status

200

Headers

Content-Type: application/json; charset=utf-8

Body

{
  "status": "success",
  "contract": {
    "id": "oYG9dyXNwAD8k7LZ",
    "your_role": "seller",
    "can_be_canceled": false,
    "offer_id": "h8JydgFZtzgzunW5",
    "price": "7000.00",
    "value": "7210.79",
    "currency_code": "EUR",
    "volume": "11.00000000",
    "asset_code": "BTC",
    "comment": "Sell me bitcoins, I agree to the terms!",
    "confirmations": 2,
    "payment_window_seconds_left": 3599762000,
    "payment_window_time_left_seconds": 3599762000,
    "payment_window_minutes": 60,
    "depositing_window_minutes": 30,
    "depositing_window_time_left_seconds": null,
    "status": "completed",
    "dispute_status": null,
    "payment_method_instruction": {
      "payment_method_id": "4446",
      "details": "Wire transfer to account #123123"
    },
    "volume_breakdown": {
      "goes_to_buyer": "10.78000000",
      "exchange_fee": "0.22000000",
      "exchange_fee_in_fiat": "770.00",
      "transaction_fee": "0.00003291"
    },
    "country": "Country 116",
    "country_code": "Country Code 116",
    "created_at": "2020-07-14T13:45:46Z",
    "counterparty": {
      "login": "us4r15",
      "avatar_url": "http://example.org/assets/default_avatar-f5b0258802df64cd87d94b95a1faed32b1b464bfb9b1cef2a10f6c30ddc91158.svg",
      "online_status": "offline",
      "rating": null,
      "trades_count": 1,
      "url": "http://hodldev.local:3001/accounts/us4r15",
      "verified": false,
      "verified_by": null,
      "strong_hodler": false,
      "country": "Country 112",
      "country_code": "Country Code 112",
      "average_payment_time_minutes": 0,
      "average_release_time_minutes": null,
      "days_since_last_trade": 0,
      "blocked_by": 0
    },
    "escrow": {
      "address": "2N8sSFGeqPhv9wUjC33Q7uB7GgTua7xATaK",
      "witness_script": "5221026ca0928f093b75969f28011e5d60a5f2df32b73c65a564bc0a47f0cd7e5bfb2b2103b0732595adf4a0ffbb350a1a33a819fda948a0e792e3cd225cf19448562a3d022103b0732595adf4a0ffbb350a1a33a819fda948a0e792e3cd225cf19448562a3d0253ae",
      "index": 222,
      "you_confirmed": true,
      "counterparty_confirmed": true,
      "confirmations": 0,
      "amount_deposited": "11.00000000",
      "amount_released": null,
      "deposit_transaction_id": null,
      "release_transaction_id": null
    }
  }
}

Starting dispute on the contract

Starts the dispute.

Dispute could be started:

  • by the seller — when the contract status is "paid"
  • by the buyer — when the contract status is "paid" and payment window has expired

Endpoint

POST /api/v1/contracts/:id/dispute

Parameters

Name Description
id

Contract ID

Request

Route

POST /api/v1/contracts/toMfnh42h3rApMPH/dispute

Headers

Authorization: Bearer aAb2qlDKQZsS4V1gPHT9.......
Content-Type: application/json

cURL

curl "hodlhodl.com/api/v1/contracts/toMfnh42h3rApMPH/dispute" -d '' -X POST \
	-H "Authorization: Bearer aAb2qlDKQZsS4V1gPHT9......." \
	-H "Content-Type: application/json"

Response

Simulated Response

Response Fields

Name Description
contract

Contract (see Getting contract for fields description)

Status

200

Headers

Content-Type: application/json; charset=utf-8

Body

{
  "status": "success",
  "contract": {
    "id": "toMfnh42h3rApMPH",
    "your_role": "seller",
    "can_be_canceled": false,
    "offer_id": "V552OEU1W4zD39ry",
    "price": "7000.00",
    "value": "7210.79",
    "currency_code": "EUR",
    "volume": "11.00000000",
    "asset_code": "BTC",
    "comment": "Sell me bitcoins, I agree to the terms!",
    "confirmations": 2,
    "payment_window_seconds_left": 3599835000,
    "payment_window_time_left_seconds": 3599835000,
    "payment_window_minutes": 60,
    "depositing_window_minutes": 30,
    "depositing_window_time_left_seconds": null,
    "status": "disputed",
    "dispute_status": "unresolved",
    "payment_method_instruction": {
      "payment_method_id": "4448",
      "details": "Wire transfer to account #123123"
    },
    "volume_breakdown": {
      "goes_to_buyer": "10.78000000",
      "exchange_fee": "0.22000000",
      "exchange_fee_in_fiat": "770.00",
      "transaction_fee": "0.00003291"
    },
    "country": "Country 125",
    "country_code": "Country Code 125",
    "created_at": "2020-07-14T13:45:46Z",
    "counterparty": {
      "login": "us4r16",
      "avatar_url": "http://example.org/assets/default_avatar-f5b0258802df64cd87d94b95a1faed32b1b464bfb9b1cef2a10f6c30ddc91158.svg",
      "online_status": "offline",
      "rating": null,
      "trades_count": 0,
      "url": "http://hodldev.local:3001/accounts/us4r16",
      "verified": false,
      "verified_by": null,
      "strong_hodler": false,
      "country": "Country 121",
      "country_code": "Country Code 121",
      "average_payment_time_minutes": 0,
      "average_release_time_minutes": null,
      "days_since_last_trade": null,
      "blocked_by": 0
    },
    "escrow": {
      "address": "2N3CVGPvJgETZdbqkfc46jJFpXpX8v5LBaC",
      "witness_script": "522103edf82ebc5a75ee5ac8e8fdaf6d48093d81f2acaef6936bf6c810351d9d01489c21039d4b4b7b1070b004c1ca6f37d1461802e7e42c5182b6bffbefe9f8cd0af3a32821039d4b4b7b1070b004c1ca6f37d1461802e7e42c5182b6bffbefe9f8cd0af3a32853ae",
      "index": 223,
      "you_confirmed": true,
      "counterparty_confirmed": true,
      "confirmations": 0,
      "amount_deposited": "11.00000000",
      "amount_released": null,
      "deposit_transaction_id": null,
      "release_transaction_id": null
    }
  }
}

Countries

Countries resource

Listing countries

Note. Example here doesn’t list actual countries. Do an actual query to the API server to get the list.

Endpoint

GET /api/v1/countries

Request

Route

GET /api/v1/countries

Headers

Authorization: Bearer aAb2qlDKQZsS4V1gPHT9.......
Content-Type: application/json

cURL

curl -g "hodlhodl.com/api/v1/countries" -X GET \
	-H "Authorization: Bearer aAb2qlDKQZsS4V1gPHT9......." \
	-H "Content-Type: application/json"

Response

Simulated Response

Response Fields

Name Description
countries

Countries array

countries[#].code

Code

countries[#].name

Name

countries[#].native_name

Name as written in the country’s language

countries[#].currency_code

State currency code

countries[#].currency_name

State currency name

Status

200

Headers

Content-Type: application/json; charset=utf-8

Body

{
  "status": "success",
  "countries": [
    {
      "code": "AU",
      "name": "Australia",
      "native_name": "Australia",
      "currency_code": "AUD",
      "currency_name": "Australian dollar"
    },
    {
      "code": "RU",
      "name": "Russia",
      "native_name": "Россия",
      "currency_code": "RUB",
      "currency_name": "Russian ruble"
    }
  ]
}

Currencies

Currencies resource

Listing currencies

Note. Example here doesn’t list actual currencies. Do an actual query to the API server to get the list.

Endpoint

GET /api/v1/currencies

Request

Route

GET /api/v1/currencies

Headers

Authorization: Bearer aAb2qlDKQZsS4V1gPHT9.......
Content-Type: application/json

cURL

curl -g "hodlhodl.com/api/v1/currencies" -X GET \
	-H "Authorization: Bearer aAb2qlDKQZsS4V1gPHT9......." \
	-H "Content-Type: application/json"

Response

Simulated Response

Response Fields

Name Description
currencies

Currencies array

currency[#].code

Code

currency[#].name

Name

currency[#].type

“fiat” or “crypto”

Status

200

Headers

Content-Type: application/json; charset=utf-8

Body

{
  "status": "success",
  "currencies": [
    {
      "code": "AUD",
      "name": "Australian dollar",
      "type": "fiat"
    },
    {
      "code": "RUB",
      "name": "Russian ruble",
      "type": "fiat"
    }
  ]
}

Exchange rate providers

Exchange rate providers resource

Listing exchange rate providers

Note. Example here doesn’t list actual exchange rate providers. Do an actual query to the API server to get the list.

Endpoint

GET /api/v1/exchange_rate_providers

Request

Route

GET /api/v1/exchange_rate_providers

Headers

Authorization: Bearer aAb2qlDKQZsS4V1gPHT9.......
Content-Type: application/json

cURL

curl -g "hodlhodl.com/api/v1/exchange_rate_providers" -X GET \
	-H "Authorization: Bearer aAb2qlDKQZsS4V1gPHT9......." \
	-H "Content-Type: application/json"

Response

Simulated Response

Response Fields

Name Description
exchange_rate_providers

Exchange rate providers array

exchange_rate_providers[#].name

Name

exchange_rate_providers[#].currency_codes

Array of currency codes

Status

200

Headers

Content-Type: application/json; charset=utf-8

Body

{
  "status": "success",
  "exchange_rate_providers": [
    {
      "name": "Bitpay",
      "currency_codes": [
        "AUD",
        "BCH",
        "USD"
      ]
    },
    {
      "name": "Bitstamp",
      "currency_codes": [
        "AUD",
        "BCH",
        "ETH",
        "LTC",
        "USD",
        "XRP"
      ]
    }
  ]
}

Notifications

Notifications resource

Reading notifications

This method fetches all unread notification and marks them as read.

A client must show all notifications which it fetched.

A client must show all textual fields of the notification: title, body, link. Link should be clickable. Clients should show notifications in a way suitable for a particular UI environment which client targets, ensuring best user experience.

Note: body of a notification could be multiline (standard line feeds \n will be used). Title, body and link are all plain-text (no HTML markup).

Endpoint

POST /api/v1/notifications/read

Request

Route

POST /api/v1/notifications/read

Headers

Authorization: Bearer aAb2qlDKQZsS4V1gPHT9.......
Content-Type: application/json

cURL

curl "hodlhodl.com/api/v1/notifications/read" -d '' -X POST \
	-H "Authorization: Bearer aAb2qlDKQZsS4V1gPHT9......." \
	-H "Content-Type: application/json"

Response

Simulated Response

Response Fields

Name Description
notifications

Notifications array

notifications[#].id

ID of notification

notifications[#].title

Title

notifications[#].body

Body (could contain \n; could be null) 1

notifications[#].link

Hyperlink (could be null)

Status

200

Headers

Content-Type: application/json; charset=utf-8

Body

{
  "status": "success",
  "notifications": [
    {
      "id": "3423",
      "title": "Hello, this is a notification!",
      "body": "Dear user. The seller in one of your contracts deposited bitcoins.",
      "link": "https://hodlhodl.com/contracts/123"
    },
    {
      "id": "3424",
      "title": "Hello, this is a notification!",
      "body": "Dear user. The seller in one of your contracts deposited bitcoins.",
      "link": "https://hodlhodl.com/contracts/123"
    },
    {
      "id": "3425",
      "title": "Hello, this is a notification!",
      "body": "Dear user. The seller in one of your contracts deposited bitcoins.",
      "link": "https://hodlhodl.com/contracts/123"
    }
  ]
}

Offers

Offers resource

Getting offer

Note 1: total fee consists of “trading fee” and “transaction fee”. Trading fee is calculated as minimum among buyer and seller fee. User fee is calculated as base fee rate minus discount for online presence. Transaction fee is estimated accroding to current blockchain situation.

Note 2: list of all payment methods, used across the exchange, could be obtained by querying “Payment methods” resource.

Note 3: country and country_code will be "Global" for worldwide offers/traders.

Endpoint

GET /api/v1/offers/:id

Parameters

Name Description
id

Offer ID

Request

Route

GET /api/v1/offers/WnMI7IiGUuSClLYY

Headers

Authorization: Bearer aAb2qlDKQZsS4V1gPHT9.......
Content-Type: application/json

cURL

curl -g "hodlhodl.com/api/v1/offers/WnMI7IiGUuSClLYY" -X GET \
	-H "Authorization: Bearer aAb2qlDKQZsS4V1gPHT9......." \
	-H "Content-Type: application/json"

Response

Simulated Response

Response Fields

Name Description
offer

Offer resource

offer.id

ID

offer.version

Version

offer.asset_code

Asset code ("BTC" or "BTCLN")

offer.searchable

Will appear in the search? (true or false)

Note that even non-private offer can be unlisted if it’s not enabled or blocked. This field will show whether the offer will actually be shown in the search.

offer.country

Country name (or "Global")

offer.country_code

Country code (or "Global")

offer.working_now

Is current time between working_hours_start_utc and working_hours_end_utc? (true or false)

offer.side

"buy" or "sell"

offer.title

Title

offer.description

Description

offer.currency_code

Currency code

offer.price

Price (in currency_code fiat currency)

offer.min_amount

Minimal trade amount (in currency_code fiat currency)

offer.max_amount

Maximal trade amount (in currency_code fiat currency)

offer.first_trade_limit

First trade limit (in currency_code fiat currency)

offer.for_experienced_users

Allow create a contract with experienced users only? (true or false)

An “Experienced user” is a user who has successfully completed at least one contract and is therefore familiar with the process of trading on Hodl Hodl.

This condition is applicable only for public offers and doesn’t apply to private offers.

offer.fee

Fee details (all in fractions of 1) 1

offer.fee.author_fee_rate

Offer’s creator fee rate

offer.fee.your_fee_rate

Your fee rate (only available in Getting offer method)

offer.fee.transaction_fee

Transaction fee estimation (only available in Getting offer method)

offer.fee.exchange_fee

Trading fee (only available in Getting offer method)

offer.balance

Balance (i.e. maximum sum of all contracts yet to be created) (in currency_code fiat currency)

offer.payment_window_minutes

Payment window

offer.confirmations

Blockchain confirmations required for deposit transaction in order for Contract to be considered "Deposited"

offer.payment_methods

Payment methods

Note: only present for “buy” offers.

offer.payment_methods.id

ID of the payment method

offer.payment_methods.type

Type of the payment method

offer.payment_methods.name

Name of the payment method

offer.payment_method_instructions

Accepted payment methods with instructions 2

Note: only present for “sell” offers.

offer.payment_method_instructions.id

ID of the instruction

offer.payment_method_instructions.version

Version

offer.payment_method_instructions.payment_method_id

ID of the instruction’s payment method

offer.payment_method_instructions.payment_method_type

Type of the instruction’s payment method

offer.payment_method_instructions.payment_method_name

Name of the instruction’s payment method

offer.payment_method_instructions.details

Text of the instruction (only shows in Getting offer method for the offer creator)

offer.trader

Offer creator information

offer.trader.login

Login

offer.trader.online_status

"online", "recently_online" or "offline"

offer.trader.rating

Rating (as fraction of 1)

offer.trader.trades_count

Number of conducted trades

offer.trader.url

Hodlhodl website URL

offer.trader.verified

Verified? (true or false)

offer.trader.verified_by

Login of the Strong Hodler who verified this user

offer.trader.strong_hodler

Strong Hodler? (true or false)

Strong Hodler is a member of Hodl Hodl volunteer team that we’re working directly with.

offer.trader.country

Country name (or "Global")

offer.trader.country_code

Country code (or "Global")

offer.trader.average_payment_time_minutes

Average payment time (in minutes)

offer.trader.average_release_time_minutes

Average release time (in minutes)

offer.trader.days_since_last_trade

Number of days since last trade

offer.trader.blocked_by

How many traders blocked this user

The following is shown only for the Offer’s creator in the Getting offer method:

offer.created_at

Creation datetime in UTC, ISO8601 (YYYY-MM-DDThh:mm:ssZ)

offer.price_source

"fixed_value", "exchange_rate" or "expression"

offer.working_hours_start_utc

Working hours start in UTC (HH:MM). Only half hour increments are allowed.

Note: unlike in the website, UTC is used here instead of user’s timezone.

offer.working_hours_end_utc

Working hours end in UTC (HH:MM). Only half hour increments are allowed.

Note: unlike in the website, UTC is used here instead of user’s timezone.

offer.enabled

Enabled? (true or false)

Only the offer’s creator will be able to access an offer if it is not enabled. Trades won’t be conducted. (This is the same as ‘Enabled’ checkbox in the web interface.)

offer.private

Hide the offer from search results? (true or false)

Only non-private offers will appear in the search/list website pages and API responses. (This option is the same as ‘Private’ checkbox in the website form.)

offer.configured_max_amount

Configured by the Offer’s creator maximum amount

The following is shown only for the Offer’s creator in the Getting offer method and if price_source is "exchange_rate" (otherwise they will be null)

offer.exchange_rate_provider

Exchange rate provider name (null if the Offer is fixed price)

offer.exchange_price_deviation

Difference between the offer’s price and price on the exchange (null if the Offer is fixed price)

offer.exchange_price_sign

"+" or "-" (null if the Offer is fixed price)

offer.exchange_price_unit

"%" or "currency" (null if the Offer is fixed price)

The followind is shown only for the Offer’s creator in the Getting offer method and if price_source is "expression" (otherwise they will be null)

offer.price_expression

Expression that is evaluated to calculate price

Status

200

Headers

Content-Type: application/json; charset=utf-8

Body

{
  "status": "success",
  "offer": {
    "id": "WnMI7IiGUuSClLYY",
    "version": "219ed5qk",
    "asset_code": "BTC",
    "searchable": true,
    "country": "Country 154",
    "country_code": "Country Code 154",
    "working_now": true,
    "side": "sell",
    "title": "Offer's title",
    "description": "You give me money, I'll give you bitcoins",
    "currency_code": "USD",
    "price": "725.53",
    "min_amount": "0.01",
    "max_amount": "10000.00",
    "first_trade_limit": null,
    "fee": {
      "author_fee_rate": "0.02000000",
      "your_fee_rate": "0.02000000",
      "transaction_fee": "0.00003291",
      "exchange_fee": "0.02000000"
    },
    "balance": null,
    "payment_window_minutes": 60,
    "confirmations": 1,
    "payment_method_instructions": [
      {
        "id": "4585",
        "version": "219ed5qi",
        "payment_method_id": "4450",
        "payment_method_type": "Online payment system",
        "payment_method_name": "Yandex Money 11"
      }
    ],
    "trader": {
      "login": "us4r18",
      "avatar_url": "http://example.org/assets/default_avatar-f5b0258802df64cd87d94b95a1faed32b1b464bfb9b1cef2a10f6c30ddc91158.svg",
      "online_status": "offline",
      "rating": null,
      "trades_count": 0,
      "url": "http://hodlhodl.com/accounts/us4r18",
      "verified": false,
      "verified_by": null,
      "strong_hodler": false,
      "country": "Country 150",
      "country_code": "Country Code 150",
      "average_payment_time_minutes": null,
      "average_release_time_minutes": null,
      "days_since_last_trade": null,
      "blocked_by": 0
    }
  }
}

Searching/listing offers

Note 1. All filters could be ommitted.

Endpoint

GET /api/v1/offers

Parameters

Name Description
pagination.limit

Number of records to return (default 50, maximum 100)

pagination.offset

Number of records to skip (e.g. 50 for second page of results with the default limit)

filters.asset_code

Asset code (default "BTC" or "BTCLN")

filters.side

"buy" or "sell"

filters.include_global

Include global offers? (true or false, default false)

Note: if this parameter is true, then global offers will be included in addition to ones select by country filter.

filters.only_working_now

Include only offers which working hours include current time? (true or false, default false)

filters.country

Country (code or name)

filters.currency_code

Currency code

filters.payment_method_id

ID of payment method (see Payment methods/Listing payment methods)

Note: if this parameter is set, then payment_method_type and payment_method_name will be ignored.

filters.payment_method_type

Type of payment method

filters.payment_method_name

Name of payment method

filters.volume

Volume (min. volume <= given value and max. volume >= given value)

filters.payment_window_minutes_max

Maximum payment window (in minutes)

filters.user_average_payment_time_minutes_max

Offer’s creator maximum payment time (in minutes)

filters.user_average_release_time_minutes_max

Offer’s creator maximum average release time (in minutes)

sort.direction

"asc" for ascending order (default) or "desc" for descdending

sort.by

Field to sort by, possible values:

  • "price" — offer’s price (default)
  • "payment_window_minutes" — offer’s payment window (in minutes)
  • "user_average_payment_time_minutes" — an offer creator’s average payment time
  • "user_average_release_time_minutes" — an offer creator’s average release time
  • "rating" — an offer creator’s rating

Request

Route

GET /api/v1/offers?sort[by]=payment_window_minutes&sort[direction]=asc&filters[user_average_release_time_minutes_max]=25

Headers

Authorization: Bearer aAb2qlDKQZsS4V1gPHT9.......
Content-Type: application/json

Query Parameters as JSON

{
  "sort": {
    "by": "payment_window_minutes",
    "direction": "asc"
  },
  "filters": {
    "user_average_release_time_minutes_max": "25"
  }
}

cURL

curl -g "hodlhodl.com/api/v1/offers?sort[by]=payment_window_minutes&sort[direction]=asc&filters[user_average_release_time_minutes_max]=25" -X GET \
	-H "Authorization: Bearer aAb2qlDKQZsS4V1gPHT9......." \
	-H "Content-Type: application/json"

Response

Simulated Response

Response Fields

Name Description
offers

Array of Offers (see Getting offer for fields description)

Status

200

Headers

Content-Type: application/json; charset=utf-8

Body

{
  "status": "success",
  "filters": {
    "user_average_release_time_minutes_max": 25,
    "include_global": true,
    "only_working_now": false
  },
  "sort": {
    "by": "payment_window_minutes",
    "direction": "asc"
  },
  "pagination": {
  },
  "offers": [
    {
      "id": "8DXqEvBITCPVPMMa",
      "version": "219ed5r2",
      "asset_code": "BTC",
      "searchable": true,
      "country": "Country 168",
      "country_code": "Country Code 168",
      "working_now": true,
      "side": "sell",
      "title": null,
      "description": "You give me money, I'll give you bitcoins",
      "currency_code": "USD",
      "price": "725.53",
      "min_amount": "0.01",
      "max_amount": "10000.00",
      "first_trade_limit": null,
      "fee": {
        "author_fee_rate": "0.02000000"
      },
      "balance": null,
      "payment_window_minutes": 35,
      "confirmations": 1,
      "payment_method_instructions": [
        {
          "id": "4587",
          "version": "219ed5r1",
          "payment_method_id": "4452",
          "payment_method_type": "Online payment system",
          "payment_method_name": "Yandex Money 13"
        }
      ],
      "trader": {
        "login": "us4r19",
        "avatar_url": "http://example.org/assets/default_avatar-f5b0258802df64cd87d94b95a1faed32b1b464bfb9b1cef2a10f6c30ddc91158.svg",
        "online_status": "offline",
        "rating": "0.90",
        "trades_count": 0,
        "url": "http://hodlhodl.com/accounts/us4r19",
        "verified": false,
        "verified_by": null,
        "strong_hodler": false,
        "country": "Country 159",
        "country_code": "Country Code 159",
        "average_payment_time_minutes": 20,
        "average_release_time_minutes": 20,
        "days_since_last_trade": null,
        "blocked_by": 0
      }
    },
    {
      "id": "epq7afk2IpTr5RdT",
      "version": "219ed5r0",
      "asset_code": "BTC",
      "searchable": true,
      "country": "Country 167",
      "country_code": "Country Code 167",
      "working_now": true,
      "side": "sell",
      "title": null,
      "description": "You give me money, I'll give you bitcoins",
      "currency_code": "USD",
      "price": "725.53",
      "min_amount": "0.01",
      "max_amount": "10000.00",
      "first_trade_limit": null,
      "fee": {
        "author_fee_rate": "0.02000000"
      },
      "balance": null,
      "payment_window_minutes": 40,
      "confirmations": 1,
      "payment_method_instructions": [
        {
          "id": "4586",
          "version": "219ed5qz",
          "payment_method_id": "4451",
          "payment_method_type": "Online payment system",
          "payment_method_name": "Yandex Money 12"
        }
      ],
      "trader": {
        "login": "us4r19",
        "avatar_url": "http://example.org/assets/default_avatar-f5b0258802df64cd87d94b95a1faed32b1b464bfb9b1cef2a10f6c30ddc91158.svg",
        "online_status": "offline",
        "rating": "0.90",
        "trades_count": 0,
        "url": "http://hodlhodl.com/accounts/us4r19",
        "verified": false,
        "verified_by": null,
        "strong_hodler": false,
        "country": "Country 159",
        "country_code": "Country Code 159",
        "average_payment_time_minutes": 20,
        "average_release_time_minutes": 20,
        "days_since_last_trade": null,
        "blocked_by": 0
      }
    }
  ]
}

Listing my offers

This method will return all your existing offers, recently created first.

Endpoint

GET /api/v1/offers/my

Request

Route

GET /api/v1/offers/my

Headers

Authorization: Bearer aAb2qlDKQZsS4V1gPHT9.......
Content-Type: application/json

cURL

curl -g "hodlhodl.com/api/v1/offers/my" -X GET \
	-H "Authorization: Bearer aAb2qlDKQZsS4V1gPHT9......." \
	-H "Content-Type: application/json"

Response

Simulated Response

Response Fields

Name Description
offers

Array of Offers (see Getting offer for fields description)

Status

200

Headers

Content-Type: application/json; charset=utf-8

Body

{
  "status": "success",
  "offers": [
    {
      "id": "J9QTDXmo5tGKOuAI",
      "version": "219ed5rm",
      "asset_code": "BTC",
      "searchable": true,
      "country": "Country 179",
      "country_code": "Country Code 179",
      "working_now": true,
      "side": "sell",
      "title": null,
      "description": "You give me money, I'll give you bitcoins",
      "currency_code": "USD",
      "price": "725.53",
      "min_amount": "0.01",
      "max_amount": "10000.00",
      "first_trade_limit": null,
      "fee": {
        "author_fee_rate": "0.02000000",
        "your_fee_rate": "0.02000000",
        "transaction_fee": "0.00003291",
        "exchange_fee": "0.02000000"
      },
      "balance": null,
      "payment_window_minutes": 35,
      "confirmations": 1,
      "payment_method_instructions": [
        {
          "id": "4590",
          "version": "219ed5rl",
          "payment_method_id": "4455",
          "payment_method_type": "Online payment system",
          "payment_method_name": "Yandex Money 16",
          "details": "Send money over to account 123"
        }
      ],
      "trader": {
        "login": "test_user",
        "avatar_url": "http://example.org/assets/default_avatar-f5b0258802df64cd87d94b95a1faed32b1b464bfb9b1cef2a10f6c30ddc91158.svg",
        "online_status": "offline",
        "rating": null,
        "trades_count": 0,
        "url": "http://hodlhodl.com/accounts/test_user",
        "verified": false,
        "verified_by": null,
        "strong_hodler": false,
        "country": "Country 170",
        "country_code": "Country Code 170",
        "average_payment_time_minutes": null,
        "average_release_time_minutes": null,
        "days_since_last_trade": null,
        "blocked_by": 0
      },
      "created_at": "2020-07-14T13:45:47Z",
      "working_hours_start_utc": "12:45",
      "working_hours_end_utc": "14:45",
      "enabled": true,
      "private": false,
      "for_experienced_users": false,
      "price_source": "exchange_rate",
      "exchange_rate_provider": "Bitstamp",
      "exchange_price_deviation": "2.00000000",
      "exchange_price_sign": "+",
      "exchange_price_unit": "%",
      "configured_max_amount": "10000.00000000"
    },
    {
      "id": "ZydVG9QMA66CaxYU",
      "version": "219ed5rj",
      "asset_code": "BTC",
      "searchable": true,
      "country": "Country 178",
      "country_code": "Country Code 178",
      "working_now": true,
      "side": "sell",
      "title": null,
      "description": "You give me money, I'll give you bitcoins",
      "currency_code": "USD",
      "price": "725.53",
      "min_amount": "0.01",
      "max_amount": "10000.00",
      "first_trade_limit": null,
      "fee": {
        "author_fee_rate": "0.02000000",
        "your_fee_rate": "0.02000000",
        "transaction_fee": "0.00003291",
        "exchange_fee": "0.02000000"
      },
      "balance": null,
      "payment_window_minutes": 40,
      "confirmations": 1,
      "payment_method_instructions": [
        {
          "id": "4589",
          "version": "219ed5ri",
          "payment_method_id": "4454",
          "payment_method_type": "Online payment system",
          "payment_method_name": "Yandex Money 15",
          "details": "Send money over to account 123"
        }
      ],
      "trader": {
        "login": "test_user",
        "avatar_url": "http://example.org/assets/default_avatar-f5b0258802df64cd87d94b95a1faed32b1b464bfb9b1cef2a10f6c30ddc91158.svg",
        "online_status": "offline",
        "rating": null,
        "trades_count": 0,
        "url": "http://hodlhodl.com/accounts/test_user",
        "verified": false,
        "verified_by": null,
        "strong_hodler": false,
        "country": "Country 170",
        "country_code": "Country Code 170",
        "average_payment_time_minutes": null,
        "average_release_time_minutes": null,
        "days_since_last_trade": null,
        "blocked_by": 0
      },
      "created_at": "2020-07-14T13:45:47Z",
      "working_hours_start_utc": "12:45",
      "working_hours_end_utc": "14:45",
      "enabled": true,
      "private": false,
      "for_experienced_users": false,
      "price_source": "exchange_rate",
      "exchange_rate_provider": "Bitstamp",
      "exchange_price_deviation": "2.00000000",
      "exchange_price_sign": "+",
      "exchange_price_unit": "%",
      "configured_max_amount": "10000.00000000"
    }
  ]
}

Fetching newly created offers

This method allows you to fetch newly created offer.

Store pagination.last_id from the first response of this method call on the client. Provide pagination.last_id as pagination.newer_than_id parameter to the next method call to fetch offers which were created strictly after the one with last_id. Repeat until all offers are fetched (offers is []).

Pseudocode to fetch all offers would look like this:

last_id = retrieve_last_id_from_local_db || null
result = fetch_new("pagination": {"newer_than_id": last_id})

while result["offers"] != []
  save_offers_to_local_db(result["offers"])

  last_id = result["pagination"]["last_id"]
  result = fetch_new("pagination": {"newer_than_id": last_id})
end

save_last_id_to_local_db(last_id)

Offers in the response will always be sorted from the oldest to the newest.

Endpoint

GET /api/v1/offers/fetch_new

Parameters

Name Description
pagination.newer_than_id

Set to pagination.last_id value from the previous request (omit it or set to known offer’s ID as initial value)

filters.asset_code

Asset code (default "BTC" or "BTCLN")

filters.side

"buy" or "sell"

filters.include_global

Include global offers? (true or false, default false)

Note: if this parameter is true, then global offers will be included in addition to ones selected by country filter.

filters.only_working_now

Include only offers which working hours include current time? (true or false, default false)

filters.country

Country (code or name)

filters.currency_code

Currency code

filters.payment_method_id

ID of payment method (see Payment methods/Listing payment methods)

Note: if this parameter is set, then payment_method_type and payment_method_name will be ignored.

filters.payment_method_type

Type of payment method (see Payment methods/Listing payment methods)

filters.payment_method_name

Name of payment method

filters.volume

Volume (min. volume <= given value <= max volume)

filters.payment_window_minutes_max

Maximum payment window (in minutes)

filters.user_average_payment_time_minutes_max

Offer’s creator maximum payment time (in minutes)

filters.user_average_release_time_minutes_max

Offer’s creator maximum average release time (in minutes)

Request

Route

GET /api/v1/offers/fetch_new?filters[user_average_release_time_minutes_max]=25&pagination[newer_than_id]=l0Bv4L30ktAk4wfm

Headers

Authorization: Bearer aAb2qlDKQZsS4V1gPHT9.......
Content-Type: application/json

Query Parameters as JSON

{
  "filters": {
    "user_average_release_time_minutes_max": "25"
  },
  "pagination": {
    "newer_than_id": "l0Bv4L30ktAk4wfm"
  }
}

cURL

curl -g "hodlhodl.com/api/v1/offers/fetch_new?filters[user_average_release_time_minutes_max]=25&pagination[newer_than_id]=l0Bv4L30ktAk4wfm" -X GET \
	-H "Authorization: Bearer aAb2qlDKQZsS4V1gPHT9......." \
	-H "Content-Type: application/json"

Response

Simulated Response

Response Fields

Name Description
offers

Array of Offers (see Offers/Getting offer for fields description)

filters

Filters values (fetched from the parameters and/or default ones)

pagination.last_id

Newest offer ID to store on the client

Status

200

Headers

Content-Type: application/json; charset=utf-8

Body

{
  "status": "success",
  "filters": {
    "user_average_release_time_minutes_max": 25,
    "include_global": true,
    "only_working_now": false
  },
  "pagination": {
    "newer_than_id": "l0Bv4L30ktAk4wfm",
    "last_id": "OdNt33STZ7AKuaVL"
  },
  "offers": [
    {
      "id": "Er6Cz1JtBvdQka2h",
      "version": "219ed5s6",
      "asset_code": "BTC",
      "searchable": true,
      "country": "Country 195",
      "country_code": "Country Code 195",
      "working_now": true,
      "side": "sell",
      "title": null,
      "description": "You give me money, I'll give you bitcoins",
      "currency_code": "USD",
      "price": "725.53",
      "min_amount": "0.01",
      "max_amount": "10000.00",
      "first_trade_limit": null,
      "fee": {
        "author_fee_rate": "0.02000000"
      },
      "balance": null,
      "payment_window_minutes": 34,
      "confirmations": 1,
      "payment_method_instructions": [
        {
          "id": "4594",
          "version": "219ed5s5",
          "payment_method_id": "4459",
          "payment_method_type": "Online payment system",
          "payment_method_name": "Yandex Money 20"
        }
      ],
      "trader": {
        "login": "us4r22",
        "avatar_url": "http://example.org/assets/default_avatar-f5b0258802df64cd87d94b95a1faed32b1b464bfb9b1cef2a10f6c30ddc91158.svg",
        "online_status": "offline",
        "rating": "0.90",
        "trades_count": 0,
        "url": "http://hodlhodl.com/accounts/us4r22",
        "verified": false,
        "verified_by": null,
        "strong_hodler": false,
        "country": "Country 185",
        "country_code": "Country Code 185",
        "average_payment_time_minutes": 20,
        "average_release_time_minutes": 20,
        "days_since_last_trade": null,
        "blocked_by": 0
      }
    },
    {
      "id": "OdNt33STZ7AKuaVL",
      "version": "219ed5s3",
      "asset_code": "BTC",
      "searchable": true,
      "country": "Country 194",
      "country_code": "Country Code 194",
      "working_now": true,
      "side": "sell",
      "title": null,
      "description": "You give me money, I'll give you bitcoins",
      "currency_code": "USD",
      "price": "725.53",
      "min_amount": "0.01",
      "max_amount": "10000.00",
      "first_trade_limit": null,
      "fee": {
        "author_fee_rate": "0.02000000"
      },
      "balance": null,
      "payment_window_minutes": 35,
      "confirmations": 1,
      "payment_method_instructions": [
        {
          "id": "4593",
          "version": "219ed5s3",
          "payment_method_id": "4458",
          "payment_method_type": "Online payment system",
          "payment_method_name": "Yandex Money 19"
        }
      ],
      "trader": {
        "login": "us4r22",
        "avatar_url": "http://example.org/assets/default_avatar-f5b0258802df64cd87d94b95a1faed32b1b464bfb9b1cef2a10f6c30ddc91158.svg",
        "online_status": "offline",
        "rating": "0.90",
        "trades_count": 0,
        "url": "http://hodlhodl.com/accounts/us4r22",
        "verified": false,
        "verified_by": null,
        "strong_hodler": false,
        "country": "Country 185",
        "country_code": "Country Code 185",
        "average_payment_time_minutes": 20,
        "average_release_time_minutes": 20,
        "days_since_last_trade": null,
        "blocked_by": 0
      }
    }
  ]
}

Creating offer

Endpoint

POST /api/v1/offers

Parameters

Name Description
offer.asset_code

Asset code (default "BTC" or "BTCLN")

offer.side

"buy" or "sell" (required)

offer.country_code

Country code (assumed Global if ommited)

offer.currency_code

Currency code (required)

Use Currencies/Listring currencies to get currency code.

offer.balance

Balance (i.e. maximum sum of all contracts yet to be created) (in currency_code fiat currency) (required)

offer.min_amount

Minimal trade amount (in currency_code fiat currency) (required)

offer.max_amount

Maximal trade amount (in currency_code fiat currency) (required, 0 for auto-adjust)

offer.first_trade_limit

First trade limit (in currency_code fiat currency)

offer.for_experienced_users

Allow create a contract with experienced users only? (true or false)

An “Experienced user” is a user who has successfully completed at least one contract and is therefore familiar with the process of trading on Hodl Hodl.

This condition is applicable only for public offers and doesn’t apply to private offers.

offer.confirmations

Blockchain confirmations required for deposit transaction in order for Contract to be considered "Deposited" (default 1)

offer.payment_window_minutes

Payment window (default 90)

offer.working_hours_start_utc

Working hours start in UTC (HH:MM) (default "00:00", half hours increments)

offer.working_hours_end_utc

Working hours end in UTC (HH:MM) (default "00:00", half hours increments)

offer.title

Title

offer.description

Description

offer.enabled

Enabled? (true or false, default false)

Only the offer’s creator will be able to access an offer if it is not enabled. Trades won’t be conducted. (This is the same as ‘Enabled’ checkbox in the web interface.)

offer.private

Hide the offer from search results? (true or false)

Only non-private offers will appear in the search/list website pages and API responses. (This option is the same as ‘Private’ checkbox in the website form.)

offer.payment_method_ids

Array of payment method IDs (see Payment methods/Listing payment methods)

Note: required only for “buy” offers.

offer.payment_method_instruction_ids

Array of payment method instruction IDs (see Payment method instructions)

Note: required only for “sell” offers.

If you want to create a fixed-price offer:

offer.price_source

"fixed_value" (required)

offer.price

Price (in currency_code fiat currency) (required)

If you want to create an offer which price follows external exchange rate:

offer.price_source

"exchange_rate" (required)

offer.exchange_rate_provider

Exchange rate provider name (required)

offer.exchange_price_deviation

Difference between the offer’s price and price on the exchange (required)

offer.exchange_price_sign

"+" or "-" (default "+")

offer.exchange_price_unit

"%" or "currency" (default "%")

If you want to create an offer with price evaluated from expression

offer.price_source

"expression" (required)

offer.price_expression

Expression to evaluate

Request

Route

POST /api/v1/offers

Headers

Authorization: Bearer aAb2qlDKQZsS4V1gPHT9.......
Content-Type: application/json

Body

{
  "offer": {
    "asset_code": "BTC",
    "currency_code": "USD",
    "price_source": "fixed_value",
    "price": 700.0,
    "balance": 20000,
    "side": "buy",
    "country_code": "AU",
    "min_amount": 1.0,
    "max_amount": 6000.0,
    "first_trade_limit": 100,
    "for_experienced_users": false,
    "confirmations": 2,
    "payment_window_minutes": 30,
    "working_hours_start_utc": "02:00",
    "working_hours_end_utc": "06:00",
    "description": "The Description",
    "title": "The Title",
    "enabled": true,
    "private": false,
    "payment_method_ids": [
      4461
    ]
  }
}

cURL

curl "hodlhodl.com/api/v1/offers" -d '{"offer":{"asset_code":"BTC","currency_code":"USD","price_source":"fixed_value","price":700.0,"balance":20000,"side":"buy","country_code":"AU","min_amount":1.0,"max_amount":6000.0,"first_trade_limit":100,"for_experienced_users":false,"confirmations":2,"payment_window_minutes":30,"working_hours_start_utc":"02:00","working_hours_end_utc":"06:00","description":"The Description","title":"The Title","enabled":true,"private":false,"payment_method_ids":[4461]}}' -X POST \
	-H "Authorization: Bearer aAb2qlDKQZsS4V1gPHT9......." \
	-H "Content-Type: application/json"

Response

Simulated Response

Response Fields

Name Description
offer

Offer (newly created; see Getting offer for fields description)

Status

200

Headers

Content-Type: application/json; charset=utf-8

Body

{
  "status": "success",
  "offer": {
    "id": "eXSxGdHMkcqgoEKh",
    "version": "219ed5so",
    "asset_code": "BTC",
    "searchable": true,
    "country": "Australia",
    "country_code": "AU",
    "working_now": false,
    "side": "buy",
    "title": "The Title",
    "description": "The Description",
    "currency_code": "USD",
    "price": "700.00",
    "min_amount": "1.00",
    "max_amount": "6000.00",
    "first_trade_limit": "100.00",
    "fee": {
      "author_fee_rate": "0.02000000",
      "your_fee_rate": "0.02000000",
      "transaction_fee": "0.00003291",
      "exchange_fee": "0.02000000"
    },
    "balance": "20000.00",
    "payment_window_minutes": 30,
    "confirmations": 2,
    "payment_methods": [
      {
        "id": "4461",
        "type": "Bank wire",
        "name": "Yandex Money 22"
      }
    ],
    "trader": {
      "login": "test_user",
      "avatar_url": "http://example.org/assets/default_avatar-f5b0258802df64cd87d94b95a1faed32b1b464bfb9b1cef2a10f6c30ddc91158.svg",
      "online_status": "offline",
      "rating": null,
      "trades_count": 0,
      "url": "http://hodlhodl.com/accounts/test_user",
      "verified": false,
      "verified_by": null,
      "strong_hodler": false,
      "country": "Country 197",
      "country_code": "Country Code 197",
      "average_payment_time_minutes": null,
      "average_release_time_minutes": null,
      "days_since_last_trade": null,
      "blocked_by": 0
    },
    "created_at": "2020-07-14T13:45:47Z",
    "working_hours_start_utc": "02:00",
    "working_hours_end_utc": "06:00",
    "enabled": true,
    "private": false,
    "for_experienced_users": false,
    "price_source": "fixed_value",
    "exchange_rate_provider": null,
    "exchange_price_deviation": null,
    "exchange_price_sign": null,
    "exchange_price_unit": null,
    "configured_max_amount": "6000.00000000"
  }
}

Updating offer

All parameters (except ID) are optional.

An attribute does’t change if the corresponding parameter isn’t set.

Parameters are the same as in Creating offer method, except it is impossible to change an offer’s asset (asset_code) or side (side).

Endpoint

PUT /api/v1/offers/:id

Parameters

Name Description
id

Offer ID (required)

offer.country_code

Country code (assumed Global if ommited)

offer.balance

Balance (i.e. maximum sum of all contracts yet to be created) (in currency_code fiat currency)

offer.min_amount

Minimal trade amount (in currency_code fiat currency)

offer.max_amount

Maximal trade amount (in currency_code fiat currency)

offer.first_trade_limit

First trade limit (in currency_code fiat currency)

offer.for_experienced_users

Allow create a contract with experienced users only? (true or false)

An “Experienced user” is a user who has successfully completed at least one contract and is therefore familiar with the process of trading on Hodl Hodl.

This condition is applicable only for public offers and doesn’t apply to private offers.

offer.confirmations

Blockchain confirmations required for deposit transaction in order for Contract to be considered "Deposited"

offer.payment_window_minutes

Payment window, in minutes

offer.working_hours_start_utc

Working hours start in UTC (HH:MM) (only half hours increments)

offer.working_hours_end_utc

Working hours end in UTC (HH:MM) (only half hours increments)

offer.title

Title

offer.description

Description

offer.enabled

Enabled? (true or false)

Only the offer’s creator will be able to access an offer if it is not enabled. Trades won’t be conducted. (This is the same as ‘Enabled’ checkbox in the web interface.)

offer.private

Hide the offer from search results? (true or false)

Only non-private offers will appear in the search/list website pages and API responses. (This option is the same as ‘Private’ checkbox in the website form.)

offer.payment_method_ids

Array of payment method IDs (see Payment methods/Listing payment methods)

Note: only use it for “buy” offers.

offer.payment_method_instruction_ids

Array of payment method instruction IDs (see Payment method instructions)

Note: only use it for “sell” offers.

If you want to update a fixed-price offer (provide none or all of the following):

offer.price_source

"fixed_value"

offer.price

Price (in currency_code fiat currency)

offer.currency_code

Currency code

Use Currencies/Listring currencies to get currency code.

If you want to update an offer which price follows external exchange rate (provide none or all of the following):

offer.price_source

"exchange_rate"

offer.exchange_rate_provider

Exchange rate provider name

offer.exchange_price_deviation

Difference between the offer’s price and price on the exchange

offer.exchange_price_sign

"+" or "-"

offer.exchange_price_unit

"%" or "currency"

offer.currency_code

Currency code

Use Currencies/Listring currencies to get currency code.

If you want to update an offer with price evaluated from expression

offer.price_source

"expression" (required)

offer.price_expression

Expression to evaluate

Request

Route

PUT /api/v1/offers/XxLINUhkgAJ8dQR3

Headers

Authorization: Bearer aAb2qlDKQZsS4V1gPHT9.......
Content-Type: application/json

Body

{
  "offer": {
    "title": "New title",
    "description": "New description"
  }
}

cURL

curl "hodlhodl.com/api/v1/offers/XxLINUhkgAJ8dQR3" -d '{"offer":{"title":"New title","description":"New description"}}' -X PUT \
	-H "Authorization: Bearer aAb2qlDKQZsS4V1gPHT9......." \
	-H "Content-Type: application/json"

Response

Simulated Response

Response Fields

Name Description
offer

Offer (which was updated; see Getting offer for fields description)

Status

200

Headers

Content-Type: application/json; charset=utf-8

Body

{
  "status": "success",
  "offer": {
    "id": "XxLINUhkgAJ8dQR3",
    "version": "219ed5t3",
    "asset_code": "BTC",
    "searchable": true,
    "country": "Country 205",
    "country_code": "Country Code 205",
    "working_now": true,
    "side": "sell",
    "title": "New title",
    "description": "New description",
    "currency_code": "USD",
    "price": "725.53",
    "min_amount": "0.01",
    "max_amount": "10000.00",
    "first_trade_limit": null,
    "fee": {
      "author_fee_rate": "0.02000000",
      "your_fee_rate": "0.02000000",
      "transaction_fee": "0.00003291",
      "exchange_fee": "0.02000000"
    },
    "balance": null,
    "payment_window_minutes": 60,
    "confirmations": 1,
    "payment_method_instructions": [
      {
        "id": "4596",
        "version": "219ed5sx",
        "payment_method_id": "4462",
        "payment_method_type": "Online payment system",
        "payment_method_name": "Yandex Money 23",
        "details": "Send money over to account 123"
      }
    ],
    "trader": {
      "login": "test_user",
      "avatar_url": "http://example.org/assets/default_avatar-f5b0258802df64cd87d94b95a1faed32b1b464bfb9b1cef2a10f6c30ddc91158.svg",
      "online_status": "offline",
      "rating": null,
      "trades_count": 0,
      "url": "http://hodlhodl.com/accounts/test_user",
      "verified": false,
      "verified_by": null,
      "strong_hodler": false,
      "country": "Country 201",
      "country_code": "Country Code 201",
      "average_payment_time_minutes": null,
      "average_release_time_minutes": null,
      "days_since_last_trade": null,
      "blocked_by": 0
    },
    "created_at": "2020-07-14T13:45:47Z",
    "working_hours_start_utc": "12:45",
    "working_hours_end_utc": "14:45",
    "enabled": true,
    "private": false,
    "for_experienced_users": false,
    "price_source": "exchange_rate",
    "exchange_rate_provider": "Bitstamp",
    "exchange_price_deviation": "2.00000000",
    "exchange_price_sign": "+",
    "exchange_price_unit": "%",
    "configured_max_amount": "10000.00000000"
  }
}

Deleting offer

Endpoint

DELETE /api/v1/offers/:id

Parameters

Name Description
id

Offer ID

Request

Route

DELETE /api/v1/offers/yujPdhTEFZ3OgUuj

Headers

Authorization: Bearer aAb2qlDKQZsS4V1gPHT9.......
Content-Type: application/json

cURL

curl "hodlhodl.com/api/v1/offers/yujPdhTEFZ3OgUuj" -d '' -X DELETE \
	-H "Authorization: Bearer aAb2qlDKQZsS4V1gPHT9......." \
	-H "Content-Type: application/json"

Response

Simulated Response

Status

204

Fetching tied to exchange price value

Price is calculated from base value - market rate taken from one of supported exchanges and deviation from that rate. Deviation can be defied in percent (+10%) or as absolute value (-200 USD).

In example below we assume that current BTC/USD rate on Bitstamp is equal to 5000.

Endpoint

GET /api/v1/offers/exchange_rate_price

Parameters

Name Description
asset_code

Cryptocurrency asset code. Currently only ‘BTC’ supported

currency_code

Fiat currency code

provider

Exchange rate provider name (see exchange rates list)

deviation

Deviation from exchange value

sign

+ or - for adding or substraction from provider rate

unit

Deviation unit. Can be % for relative values or currency for absolute values

Request

Route

GET /api/v1/offers/exchange_rate_price?asset_code=BTC&currency_code=USD&provider=Bitstamp&deviation=40&sign=%2B&unit=currency

Headers

Authorization: Bearer aAb2qlDKQZsS4V1gPHT9.......
Content-Type: application/json

Query Parameters as JSON

{
  "asset_code": "BTC",
  "currency_code": "USD",
  "provider": "Bitstamp",
  "deviation": "40",
  "sign": "+",
  "unit": "currency"
}

cURL

curl -g "hodlhodl.com/api/v1/offers/exchange_rate_price?asset_code=BTC&currency_code=USD&provider=Bitstamp&deviation=40&sign=%2B&unit=currency" -X GET \
	-H "Authorization: Bearer aAb2qlDKQZsS4V1gPHT9......." \
	-H "Content-Type: application/json"

Response

Simulated Response

Response Fields

Name Description
price

Price

Status

200

Headers

Content-Type: application/json; charset=utf-8

Body

{
  "status": "success",
  "price": "5040.00"
}

Fetching price evaluated from expression

Full expressions guide can be found in FAQ.

In example below we assume that current BTC/USD rate on Bitstamp is equal to 5000.

Endpoint

GET /api/v1/offers/expression_price

Parameters

Name Description
expression

Expression that is evaluated to calculate price

Request

Route

GET /api/v1/offers/expression_price?expression=%28Bitstamp_BTC_USD+-+200%29+*+1.1

Headers

Authorization: Bearer aAb2qlDKQZsS4V1gPHT9.......
Content-Type: application/json

Query Parameters as JSON

{
  "expression": "(Bitstamp_BTC_USD - 200) * 1.1"
}

cURL

curl -g "hodlhodl.com/api/v1/offers/expression_price?expression=%28Bitstamp_BTC_USD+-+200%29+*+1.1" -X GET \
	-H "Authorization: Bearer aAb2qlDKQZsS4V1gPHT9......." \
	-H "Content-Type: application/json"

Response

Simulated Response

Response Fields

Name Description
price

Calculated price

Status

200

Headers

Content-Type: application/json; charset=utf-8

Body

{
  "status": "success",
  "price": "5280.00"
}

Payment method instructions

Payment method instructions resource

Note. You can view (list, delete) only payment method instructions which you have created. Payment method instruction is relevant to your ‘sell’ orders — they connect general payment method (e.g. “Online payment system -> Moneygram”) with your specific details (e.g. “Pay to account No. 12345”).

Listing payment method instructions

Endpoint

GET /api/v1/payment_method_instructions

Request

Route

GET /api/v1/payment_method_instructions

Headers

Authorization: Bearer aAb2qlDKQZsS4V1gPHT9.......
Content-Type: application/json

cURL

curl -g "hodlhodl.com/api/v1/payment_method_instructions" -X GET \
	-H "Authorization: Bearer aAb2qlDKQZsS4V1gPHT9......." \
	-H "Content-Type: application/json"

Response

Simulated Response

Response Fields

Name Description
payment_method_instructions

Array of Payment method instructions (see Getting payment method instruction for fields description)”

Status

200

Headers

Content-Type: application/json; charset=utf-8

Body

{
  "status": "success",
  "payment_method_instructions": [
    {
      "id": "4598",
      "version": "219ed5ts",
      "payment_method_id": "4464",
      "name": "Bank account #1",
      "details": "Pay to account No. 12345",
      "created_at": "2020-07-14T13:45:48Z",
      "updated_at": "2020-07-14T13:45:48Z"
    },
    {
      "id": "4599",
      "version": "219ed5ts",
      "payment_method_id": "4464",
      "name": "Bank account #2",
      "details": "Pay to account No. 67890",
      "created_at": "2020-07-14T13:45:48Z",
      "updated_at": "2020-07-14T13:45:48Z"
    }
  ]
}

Getting payment method instruction

Endpoint

GET /api/v1/payment_method_instructions/:id

Parameters

Name Description
id

Payment method instruction ID

Request

Route

GET /api/v1/payment_method_instructions/4601

Headers

Authorization: Bearer aAb2qlDKQZsS4V1gPHT9.......
Content-Type: application/json

cURL

curl -g "hodlhodl.com/api/v1/payment_method_instructions/4601" -X GET \
	-H "Authorization: Bearer aAb2qlDKQZsS4V1gPHT9......." \
	-H "Content-Type: application/json"

Response

Simulated Response

Response Fields

Name Description
payment_method_instruction

Payment method instruction

payment_method_instruction.id

ID

payment_method_instruction.version

Version

payment_method_instruction.payment_method_id

Payment method ID

payment_method_instruction.name

Name (visible only to you)

payment_method_instruction.details

Text of the instruction

payment_method_instruction.created_at

Date-time of creation (ISO 8601)

payment_method_instruction.updated_at

Date-time of last update (ISO 8601)

Status

200

Headers

Content-Type: application/json; charset=utf-8

Body

{
  "status": "success",
  "payment_method_instruction": {
    "id": "4601",
    "version": "219ed5tz",
    "payment_method_id": "4465",
    "name": "Bank account #1",
    "details": "Pay to account No. 12345",
    "created_at": "2020-07-14T13:45:48Z",
    "updated_at": "2020-07-14T13:45:48Z"
  }
}

Deleting payment method instruction

Endpoint

DELETE /api/v1/payment_method_instructions/:id

Parameters

Name Description
id

Payment method instruction ID

Request

Route

DELETE /api/v1/payment_method_instructions/4602

Headers

Authorization: Bearer aAb2qlDKQZsS4V1gPHT9.......
Content-Type: application/json

cURL

curl "hodlhodl.com/api/v1/payment_method_instructions/4602" -d '' -X DELETE \
	-H "Authorization: Bearer aAb2qlDKQZsS4V1gPHT9......." \
	-H "Content-Type: application/json"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8

Body

{
  "status": "success"
}

Creating payment method instruction

Endpoint

POST /api/v1/payment_method_instructions

Parameters

Name Description
payment_method_instruction.payment_method_id

Payment method ID

payment_method_instruction.name

Name (visible only to you)

payment_method_instruction.details

Text of the instruction

Request

Route

POST /api/v1/payment_method_instructions

Headers

Authorization: Bearer aAb2qlDKQZsS4V1gPHT9.......
Content-Type: application/json

Body

{
  "payment_method_instruction": {
    "name": "Bank account #1",
    "details": "Pay to account No. 12345",
    "payment_method_id": 4469
  }
}

cURL

curl "hodlhodl.com/api/v1/payment_method_instructions" -d '{"payment_method_instruction":{"name":"Bank account #1","details":"Pay to account No. 12345","payment_method_id":4469}}' -X POST \
	-H "Authorization: Bearer aAb2qlDKQZsS4V1gPHT9......." \
	-H "Content-Type: application/json"

Response

Simulated Response

Response Fields

Name Description
payment_method_instruction

Payment method instruction (see Getting payment method instruction for fields description)

Status

200

Headers

Content-Type: application/json; charset=utf-8

Body

{
  "status": "success",
  "payment_method_instruction": {
    "id": "4605",
    "version": "219ed5ut",
    "payment_method_id": "4469",
    "name": "Bank account #1",
    "details": "Pay to account No. 12345",
    "created_at": "2020-07-14T13:45:48Z",
    "updated_at": "2020-07-14T13:45:48Z"
  }
}

Payment methods

Payment methods resource

Listing payment methods

Note. Payment method type is one of the following:

  • "Bank wire"
  • "Cash"
  • "Cryptocurrency"
  • "Online payment system"

Endpoint

GET /api/v1/payment_methods

Parameters

Name Description
filters.country

Country name or code ("Global" to list global payment methods, omit to return all payment methods)

Request

Route

GET /api/v1/payment_methods?filters[country]=China

Headers

Authorization: Bearer aAb2qlDKQZsS4V1gPHT9.......
Content-Type: application/json

Query Parameters as JSON

{
  "filters": {
    "country": "China"
  }
}

cURL

curl -g "hodlhodl.com/api/v1/payment_methods?filters[country]=China" -X GET \
	-H "Authorization: Bearer aAb2qlDKQZsS4V1gPHT9......." \
	-H "Content-Type: application/json"

Response

Simulated Response

Response Fields

Name Description
payment_methods

Payment methods array

payment_methods[#].id

ID

payment_methods[#].type

Type

payment_methods[#].name

Name

payment_methods[#].country_codes

Array of country codes

payment_methods[#].description

Description

payment_methods[#].discounted

Discounted? (true or false)

payment_methods[#].global

Global? (true or false)

Status

200

Headers

Content-Type: application/json; charset=utf-8

Body

{
  "status": "success",
  "filters": {
    "country": "China"
  },
  "payment_methods": [
    {
      "id": "4472",
      "type": "Bank wire",
      "name": "Example payment system (two countries)",
      "country_codes": [
        "CHN"
      ],
      "description": {
      },
      "discounted": false,
      "global": false
    },
    {
      "id": "4471",
      "type": "Online payment system",
      "name": "Example payment system (single country)",
      "country_codes": [
        "CHN"
      ],
      "description": {
      },
      "discounted": false,
      "global": false
    }
  ]
}

Users

Users resource

Getting myself

This method will return information on current user.

Endpoint

GET /api/v1/users/me

Request

Route

GET /api/v1/users/me

Headers

Authorization: Bearer aAb2qlDKQZsS4V1gPHT9.......
Content-Type: application/json

cURL

curl -g "hodlhodl.com/api/v1/users/me" -X GET \
	-H "Authorization: Bearer aAb2qlDKQZsS4V1gPHT9......." \
	-H "Content-Type: application/json"

Response

Simulated Response

Response Fields

Name Description
user.login

Login

user.avatar_url

Avatar URL

user.online_status

"online", "recently_online" or "offline"

user.rating

Rating (as fraction of 1)

user.trades_count

Number of conducted trades

user.url

Hodlhodl website URL

user.verified

Verified? (true or false)

user.verified_by

Login of the Strong Hodler who verified this user

user.strong_hodler

Strong Hodler? (true or false)

Strong Hodler is a member of Hodl Hodl volunteer team that we’re working directly with.

user.country

Country name (or "Global")

user.country_code

Country code (or "Global")

user.average_payment_time_minutes

Average payment time (in minutes)

user.average_release_time_minutes

Average release time (in minutes)

user.days_since_last_trade

Number of days since last trade

user.blocked_by

How many traders blocked this user

user.encrypted_seed

Encrypted seed

user.hide_sensitive_info_from_notifications

If enabled, e-mail and Telegram notifications will not contain sensitive information

Status

200

Headers

Content-Type: application/json; charset=utf-8

Body

{
  "status": "success",
  "user": {
    "login": "test_user",
    "avatar_url": "http://example.org/assets/default_avatar-f5b0258802df64cd87d94b95a1faed32b1b464bfb9b1cef2a10f6c30ddc91158.svg",
    "online_status": "offline",
    "rating": null,
    "trades_count": 0,
    "url": "http://hodlhodl.com/accounts/test_user",
    "verified": false,
    "verified_by": null,
    "strong_hodler": false,
    "country": "Country 261",
    "country_code": "Country Code 261",
    "average_payment_time_minutes": null,
    "average_release_time_minutes": null,
    "days_since_last_trade": null,
    "blocked_by": 0,
    "encrypted_seed": "12345",
    "hide_sensitive_info_from_notifications": null
  }
}