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>

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

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

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.

Punto de llegada

GET /api/v1/countries

Solicitud

Ruta

GET /api/v1/countries

Encabezados

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"

Respuesta

Simulated Response

Campos de respuesta

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

Estado

200

Encabezados

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

Cuerpo

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

Punto de llegada

GET /api/v1/currencies

Solicitud

Ruta

GET /api/v1/currencies

Encabezados

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"

Respuesta

Simulated Response

Campos de respuesta

Name Description
currencies

Currencies array

currency[#].code

Code

currency[#].name

Name

currency[#].type

“fiat” or “crypto”

Estado

200

Encabezados

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

Cuerpo

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

Punto de llegada

GET /api/v1/exchange_rate_providers

Solicitud

Ruta

GET /api/v1/exchange_rate_providers

Encabezados

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"

Respuesta

Simulated Response

Campos de respuesta

Name Description
exchange_rate_providers

Exchange rate providers array

exchange_rate_providers[#].name

Name

exchange_rate_providers[#].currency_codes

Array of currency codes

Estado

200

Encabezados

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

Cuerpo

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

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.

Punto de llegada

GET /api/v1/offers/:id

Parametros

Name Description
id

Offer ID

Solicitud

Ruta

GET /api/v1/offers/sYtayht45ABXGCiN

Encabezados

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

cURL

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

Respuesta

Simulated Response

Campos de respuesta

Name Description
offer

Offer resource

offer.id

ID

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.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: for “sell” orders this field will be present:

  • in “Listing offers” method;
  • in “Getting offer” method when viewing other person’s Offer.
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.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.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

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" or "exchange_rate"

offer.payment_method_instructions

Accepted payment methods with instructions 2

Note: present only for “sell” offers.

offer.payment_method_instructions.id

ID of the instruction

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

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)

Estado

200

Encabezados

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

Cuerpo

{
  "status": "success",
  "offer": {
    "id": "sYtayht45ABXGCiN",
    "asset_code": "BTC",
    "searchable": true,
    "country": "Country 21",
    "country_code": "Country Code 21",
    "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": 0,
    "payment_methods": [
      {
        "id": 27,
        "type": "Online payment system",
        "name": "Yandex Money 1"
      }
    ],
    "trader": {
      "login": "us4r1",
      "online_status": "offline",
      "rating": null,
      "trades_count": 0,
      "url": "http://hodlhodl.com/accounts/us4r1",
      "verified": false,
      "country": "Country 17",
      "country_code": "Country Code 17",
      "average_payment_time_minutes": null,
      "average_release_time_minutes": null,
      "days_since_last_trade": null
    }
  }
}

Searching/listing offers

Note 1. All filters could be ommitted.

Punto de llegada

GET /api/v1/offers

Parametros

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

Solicitud

Ruta

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

Encabezados

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

Parámetros de la consulta 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"

Respuesta

Simulated Response

Campos de respuesta

Name Description
offers

Array of Offers (see Getting offer for fields description)

Estado

200

Encabezados

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

Cuerpo

{
  "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": "4iZX0d2sQ3ZM8TE4",
      "asset_code": "BTC",
      "searchable": true,
      "country": "Country 35",
      "country_code": "Country Code 35",
      "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": 0,
      "payment_methods": [
        {
          "id": 29,
          "type": "Online payment system",
          "name": "Yandex Money 3"
        }
      ],
      "trader": {
        "login": "us4r2",
        "online_status": "offline",
        "rating": "0.90",
        "trades_count": 0,
        "url": "http://hodlhodl.com/accounts/us4r2",
        "verified": false,
        "country": "Country 26",
        "country_code": "Country Code 26",
        "average_payment_time_minutes": 20,
        "average_release_time_minutes": 20,
        "days_since_last_trade": null
      }
    },
    {
      "id": "fJSz8fWYoZtKUv4P",
      "asset_code": "BTC",
      "searchable": true,
      "country": "Country 34",
      "country_code": "Country Code 34",
      "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": 0,
      "payment_methods": [
        {
          "id": 28,
          "type": "Online payment system",
          "name": "Yandex Money 2"
        }
      ],
      "trader": {
        "login": "us4r2",
        "online_status": "offline",
        "rating": "0.90",
        "trades_count": 0,
        "url": "http://hodlhodl.com/accounts/us4r2",
        "verified": false,
        "country": "Country 26",
        "country_code": "Country Code 26",
        "average_payment_time_minutes": 20,
        "average_release_time_minutes": 20,
        "days_since_last_trade": null
      }
    }
  ]
}

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.

Punto de llegada

GET /api/v1/offers/fetch_new

Parametros

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)

Solicitud

Ruta

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

Encabezados

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

Parámetros de la consulta as JSON

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

cURL

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

Respuesta

Simulated Response

Campos de respuesta

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

Estado

200

Encabezados

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

Cuerpo

{
  "status": "success",
  "filters": {
    "user_average_release_time_minutes_max": 25,
    "include_global": true,
    "only_working_now": false
  },
  "pagination": {
    "newer_than_id": "d1xxY8IflIauHE2V",
    "last_id": "0TREcaswo7ccfjJe"
  },
  "offers": [
    {
      "id": "PnSWB7eMuKFva5Jd",
      "asset_code": "BTC",
      "searchable": true,
      "country": "Country 51",
      "country_code": "Country Code 51",
      "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": 0,
      "payment_methods": [
        {
          "id": 33,
          "type": "Online payment system",
          "name": "Yandex Money 7"
        }
      ],
      "trader": {
        "login": "us4r4",
        "online_status": "offline",
        "rating": "0.90",
        "trades_count": 0,
        "url": "http://hodlhodl.com/accounts/us4r4",
        "verified": false,
        "country": "Country 41",
        "country_code": "Country Code 41",
        "average_payment_time_minutes": 20,
        "average_release_time_minutes": 20,
        "days_since_last_trade": null
      }
    },
    {
      "id": "0TREcaswo7ccfjJe",
      "asset_code": "BTC",
      "searchable": true,
      "country": "Country 50",
      "country_code": "Country Code 50",
      "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": 0,
      "payment_methods": [
        {
          "id": 32,
          "type": "Online payment system",
          "name": "Yandex Money 6"
        }
      ],
      "trader": {
        "login": "us4r4",
        "online_status": "offline",
        "rating": "0.90",
        "trades_count": 0,
        "url": "http://hodlhodl.com/accounts/us4r4",
        "verified": false,
        "country": "Country 41",
        "country_code": "Country Code 41",
        "average_payment_time_minutes": 20,
        "average_release_time_minutes": 20,
        "days_since_last_trade": null
      }
    }
  ]
}

Creating offer

Punto de llegada

POST /api/v1/offers

Parametros

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)

offer.min_amount

Minimal trade amount (in currency_code fiat currency) (default 10)

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

Solicitud

Ruta

POST /api/v1/offers

Encabezados

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

Cuerpo

{
  "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,
    "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": [
      35
    ]
  }
}

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,"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":[35]}}' -X POST \
	-H "Authorization: Bearer aAb2qlDKQZsS4V1gPHT9......." \
	-H "Content-Type: application/json"

Respuesta

Simulated Response

Estado

200

Encabezados

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

Cuerpo

{
  "status": "success",
  "offer": {
    "id": "ONKCccjD4BRuyEgn",
    "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": 35,
        "type": "Bank wire",
        "name": "Yandex Money 9"
      }
    ],
    "trader": {
      "login": "test_user",
      "online_status": "offline",
      "rating": null,
      "trades_count": 0,
      "url": "http://hodlhodl.com/accounts/test_user",
      "verified": false,
      "country": "Country 53",
      "country_code": "Country Code 53",
      "average_payment_time_minutes": null,
      "average_release_time_minutes": null,
      "days_since_last_trade": null
    },
    "created_at": "2019-12-12T17:55:55Z",
    "working_hours_start_utc": "02:00",
    "working_hours_end_utc": "06:00",
    "enabled": true,
    "private": 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).

Punto de llegada

PUT /api/v1/offers/:id

Parametros

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

Solicitud

Ruta

PUT /api/v1/offers/JHFegBUeTbWk1UCC

Encabezados

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

Cuerpo

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

cURL

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

Respuesta

Simulated Response

Estado

200

Encabezados

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

Cuerpo

{
  "status": "success",
  "offer": {
    "id": "JHFegBUeTbWk1UCC",
    "asset_code": "BTC",
    "searchable": true,
    "country": "Country 61",
    "country_code": "Country Code 61",
    "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": 0,
    "payment_method_instructions": [
      {
        "id": 27,
        "payment_method_id": 36,
        "payment_method_type": "Online payment system",
        "payment_method_name": "Yandex Money 10",
        "details": "Send money over to account 123"
      }
    ],
    "trader": {
      "login": "test_user",
      "online_status": "offline",
      "rating": null,
      "trades_count": 0,
      "url": "http://hodlhodl.com/accounts/test_user",
      "verified": false,
      "country": "Country 57",
      "country_code": "Country Code 57",
      "average_payment_time_minutes": null,
      "average_release_time_minutes": null,
      "days_since_last_trade": null
    },
    "created_at": "2019-12-12T17:55:55Z",
    "working_hours_start_utc": "16:55",
    "working_hours_end_utc": "18:55",
    "enabled": true,
    "private": 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

Punto de llegada

DELETE /api/v1/offers/:id

Parametros

Name Description
id

Offer ID

Solicitud

Ruta

DELETE /api/v1/offers/gTnQB6X13R9txRUT

Encabezados

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

cURL

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

Respuesta

Simulated Response

Estado

204

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

Punto de llegada

GET /api/v1/payment_method_instructions

Solicitud

Ruta

GET /api/v1/payment_method_instructions

Encabezados

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"

Respuesta

Simulated Response

Campos de respuesta

Name Description
payment_method_instructions

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

Estado

200

Encabezados

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

Cuerpo

{
  "status": "success",
  "payment_method_instructions": [
    {
      "id": 29,
      "payment_method_id": 38,
      "name": "Bank account #1",
      "details": "Pay to account No. 12345",
      "created_at": "2019-12-12T17:55:55Z",
      "updated_at": "2019-12-12T17:55:55Z"
    },
    {
      "id": 30,
      "payment_method_id": 38,
      "name": "Bank account #2",
      "details": "Pay to account No. 67890",
      "created_at": "2019-12-12T17:55:55Z",
      "updated_at": "2019-12-12T17:55:55Z"
    }
  ]
}

Getting payment method instruction

Punto de llegada

GET /api/v1/payment_method_instructions/:id

Parametros

Name Description
id

Payment method instruction ID

Solicitud

Ruta

GET /api/v1/payment_method_instructions/32

Encabezados

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

cURL

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

Respuesta

Simulated Response

Campos de respuesta

Name Description
payment_method_instruction

Payment method instruction

payment_method_instruction.id

ID

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)

Estado

200

Encabezados

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

Cuerpo

{
  "status": "success",
  "payment_method_instruction": {
    "id": 32,
    "payment_method_id": 39,
    "name": "Bank account #1",
    "details": "Pay to account No. 12345",
    "created_at": "2019-12-12T17:55:55Z",
    "updated_at": "2019-12-12T17:55:55Z"
  }
}

Deleting payment method instruction

Punto de llegada

DELETE /api/v1/payment_method_instructions/:id

Parametros

Name Description
id

Payment method instruction ID

Solicitud

Ruta

DELETE /api/v1/payment_method_instructions/33

Encabezados

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

cURL

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

Respuesta

Simulated Response

Estado

200

Encabezados

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

Cuerpo

{
  "status": "success"
}

Creating payment method instruction

Punto de llegada

POST /api/v1/payment_method_instructions

Parametros

Name Description
payment_method_instruction

Payment method instruction

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

Solicitud

Ruta

POST /api/v1/payment_method_instructions

Encabezados

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

Cuerpo

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

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":43}}' -X POST \
	-H "Authorization: Bearer aAb2qlDKQZsS4V1gPHT9......." \
	-H "Content-Type: application/json"

Respuesta

Simulated Response

Campos de respuesta

Name Description
payment_method_instruction

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

Estado

200

Encabezados

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

Cuerpo

{
  "status": "success",
  "payment_method_instruction": {
    "id": 36,
    "payment_method_id": 43,
    "name": "Bank account #1",
    "details": "Pay to account No. 12345",
    "created_at": "2019-12-12T17:55:55Z",
    "updated_at": "2019-12-12T17:55:55Z"
  }
}

Payment methods

Payment methods resource

Listing payment methods

Note. Payment method type is one of the following:

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

Punto de llegada

GET /api/v1/payment_methods

Parametros

Name Description
filters.country

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

Solicitud

Ruta

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

Encabezados

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

Parámetros de la consulta 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"

Respuesta

Simulated Response

Campos de respuesta

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)

Estado

200

Encabezados

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

Cuerpo

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