LocalBitcoins API Documentation

With the LocalBitcoins API you can query our public trade data and advertisements, manage your LocalBitcoins account by updating advertisements, automate trading and more.

Table of Contents

Before you start

The LocalBitcoins API is created for programmers who want to create applications to interface with LocalBitcoins. If you're not coming from a programming background you will probably have a difficult time understanding this guide. To help you get started with coding you can take a look at Code Academy that offers free courses in coding.

Certain API endpoints can be accessed without authentication, API endpoints that have to do with user account actions almost always require authentication. A few API requests can be made without authentication, but will return more information if you send authenticated API requests.

The primary way to authenticate with our API is using HMAC. HMAC is based on a secret code that only you and LocalBitcoins knows. This secret is used to sign your API requests, to ensure that it's really you who is making the requests.

The second option is OAuth 2 which can be used when you want to create applications for other users (e.g. mobile apps). OAuth 2 is not available by default, to use oAuth you need to request permission by opening a support ticket. Include in the ticket a description of your project and reasons why it can't be implemented using HMAC. Permissions are granted on a case-by-case basis.

Python Library

To help you get started with using our API we've created a python library that allows you to make API requests directly without having to implement the API yourself. You can find it here Github. This can be very useful if you're having problems calculating correct HMAC signatures.

Integrate LocalBitcoins with your E-commerce platform

If you are planning on integrating our API to your E-commerce platform, take a look at this guide.

Making requests to the API

Most API requests need to be encoded with application/x-www-form-urlencoded and sent as HTTP GET or POST requests to the appropriate API endpoint. When uploading files multipart/form-data encoding is also supported. A total of three HTTP header fields are needed:

  1. Apiauth-Key HMAC authentication key that you got when you created your HMAC authentication from the Apps dashboard.
  2. Apiauth-Nonce A unique number given with each API request. It's value needs to be greater with each API request.
  3. Apiauth-Signature Your API request signed with your HMAC secret that you got when you create your HMAC authentication from the Apps dashboard.

Apiauth-Key

To authenticate with our API you will need to register a LocalBitcoins account. After registering, visit your Apps Dashboard to create the necessary authentication keys to enable HMAC for your LocalBitcoins account.

While creating HMAC keys you can choose different permission levels:

  • read - read user-owned data.
  • write - make changes to ads, contacts, etc. but do not send or release bitcoins.
  • money - spend and release bitcoins on behalf of the user, at any time.
  • money_pin - spend and release bitcoins on behalf of the user, authorized with a PIN code.

If you don't need to send bitcoins when the API user is offline you should use the money_pin permission, which requires that the user's currently active PIN code is provided when making API requests that requires that permission.

You can request multiple permissions at the same time by selecting them while holding down ctrl or cmd with OS X.

Apiauth-Nonce

Each request also requires a nonce. A nonce is an integer number, that needs to increase with every API request. It's value has to always be greater than the previous request. It is used to ensure identical API requests have different signatures, making impossible for someone to copy your API requests and re-execute them later on.

A good trick to creating the nonce is to use the unix timestamp in milliseconds. This way you'll always get an incrementing number, just be careful to not send two API calls at the same time or they will have the same Nonce.

Most API requests need to be encoded as application/x-www-form-urlencoded, when uploading files multipart/form-data encoding is also supported. With most programming languages you can urlencode your API requests using standard functions.

With Python you can use urllib.urlencode. Example: urllib.urlencode({"foo":"bar", "baz": "quux"} which results in ?foo=bar&baz=quux.

Apiauth-Signature

The Apiauth-Signature is made by creating a string containing the following arguments and then hashing them with your HMAC authentication secret using SHA256.

  1. The Nonce. A 63 bit positive integer, for example unix timestamp as milliseconds.
  2. HMAC authentication key.
  3. API endpoint, for example, /api/wallet/.
  4. API arguments encoded as application/x-www-form-urlencoded. Files encoded as multipart/form-data.

A Python example of this can be seen below:

        import hmac
        import time
        import hashlib

        nonce = int(time.time())

        api_endpoint ="/api/notifications/"

        url = "https://localbitcoins.com/api/notifications/"

        get_or_post_params_urlencoded = ""

        message = str(nonce) + hmac_key + api_endpoint + get_or_post_params_urlencoded

        message_bytes = message.encode('utf-8')

        signature = hmac.new(hmac_secret.encode('utf-8'), msg=message_bytes, digestmod=hashlib.sha256).hexdigest().upper()
      

Interpreting responses

Return values are UTF-8 encoded JSON with the following metadata structure, which corresponds to an API request with the message return value:

        {
          "data": {"message": "Hello World!"}
        }
      

If the API request ended in an unrecoverable error, there is no data top level field. This helps against accidentally using an error message as legitimate data, creating confusing situations. Errors will also return with an appropriate HTTP error code. If the API is requested with invalid data a 400 Bad Request response is returned, but other HTTP error codes can be returned as well.

Instead there is an error field that contains an object with the fields error_code and message. The error object can contain more fields if specified on the error documentation. The error_code field is meant to be read by the application, the message field is meant to be human readable. An example error return object:

        {
          "error": {
            "message": "A strange error occurred!",
            "error_code": 7
          }
        }
      

You can find a full list of error codes and their meanings at the end of this page.

Pagination

If there are too many values to return at once the results will be paginated.

Pagination lives in the pagination field of the returned JSON object. If there are no pages, the field is undefined. If there are more than one page, the pagination field defines the next field. If you've requested the last page, only the prev field is defined. On intermediate pages the pagination object contains both the next and prev fields.

The next and prev fields are URLs pointing to the respective page. They are usable as is. Example of a paginated return value:

        {
          "data": {
            "ad_list": ...
          },
          "pagination": {
            "next": "https://localbitcoins.com/api/ads/?id__gt=50"
          }
        }
      

It is not possible to configure the maximum amount of items returned at a time. There is no concept of page numbers either.

Limiting Returned Fields

In APIs returning contacts or ads, the data fields returned can be specified. Use a request parameter of fields, which is a comma-separated list of field names. Only those fields will be returned in the data.

If the fields parameter is not given, all fields are returned. If an empty fields parameter is given, no data fields are returned. If specifying fields that do not exist in the source data, no error is given: those fields just aren't returned.

The fields specified only affect the data structure. actions, pagination etc. are not affected.

API reference

A list of all API endpoints, both public and authenticated. Certain unauthenticated endpoints return more information if you send the request authenticated.

Advertisements

Requires Authentication Endpoint HTTP method Permissions Function
/api/ads/ GET Read Returns all advertisements of the authenticated user.
/api/ad-get/{ad_id}/ GET Read Returns information on a single advertisement.
/api/ad-get/ GET Read Returns all ads from a list of comma separated ad ID's
/api/ad/{ad_id}/ POST Read, Write Update an advertisement.
/api/ad-create/ POST Read, Write Create a new advertisement.
/api/ad-delete/{ad_id}/ POST Read, Write Remove an advertisement.
/api/payment_methods/ GET - Returns a list of valid payment methods.
/api/payment_methods/{countrycode}/ GET - Returns a list of valid payment methods for a specific country code.
/api/countrycodes/ GET - List of valid countrycodes for LocalBitcoins.
/api/currencies/ GET - List of valid and recognized fiat currencies for LocalBitcoins.
/api/places/ GET - Looks up places near lat, lon and provides full URLs to buy and sell listings.

Trades

Requires Authentication Endpoint HTTP method Permissions Function
/api/feedback/{username}/ POST Read, Write Gives feedback to a user.
/api/contact_release/{contact_id}/ POST Money Release a trade (does not require money_pin).
/api/contact_release_pin/{contact_id}/ POST Money_pin Release a trade (Requires money_pin).
/api/contact_mark_as_paid/{contact_id}/ POST Read, Write Mark a trade as paid.
/api/contact_messages/{contact_id}/ GET Read Return all chat messages from a specific trade ID.
/api/contact_message_post/{contact_id}/ POST Read, Write Post a chat message to a specific trade ID.
/api/contact_dispute/{contact_id}/ POST Read, Write Starts a dispute on the trade ID.
/api/contact_cancel/{contact_id}/ POST Read, Write Cancels the trade.
/api/contact_fund/{contact_id} POST Read, Write Fund an unfunded Local trade from your LocalBitcoins wallet..
/api/contact_mark_realname/{contact_id}/ POST Read, Write Mark realname confirmation.
/api/contact_mark_identified/{contact_id}/ POST Read, Write Mark verification of trade partner as confirmed.
/api/contact_create/{ad_id}/ POST Read, Write Start a trade from an advertisement.
/api/contact_info/{contact_id}/ GET Read Return information about a single trade ID.
/api/contact_info/ GET Read Return information on your trades using a comma separated list input.

Account

Requires Authentication Endpoint HTTP method Permissions Function
/api/account_info/{username} GET - Returns public user profile information.
/api/dashboard/ GET Read Returns Open and active trades.
/api/dashboard/released/ GET Read Returns released trades.
/api/dashboard/canceled/ GET Read Returns canceled trades.
/api/dashboard/closed/ GET Read Returns closed trades.
/api/logout/ POST Read Immediately expires the current access token.
/api/myself/ GET Read, Write Return the information of the authenticated user.
/api/notifications/ GET Read Returns a list of notifications.
/api/notifications/mark_as_read/{notification_id}/ POST Read, Write Marks a specific notification as read.
/api/pincode/ POST Read Checks the given PIN code against the user's currently active PIN code.
/api/real_name_verifiers/{username}/ GET Read Returns a list of real name verifiers of the user.
/api/recent_messages/ GET Read Returns the 50 latest trade messages.

Wallet

Requires Authentication Endpoint HTTP method Permissions Function
/api/wallet/ GET Read Returns information about the token owner's wallet balance.
/api/wallet-balance/ GET Read Same as /api/wallet/ but only returns the fields message, receiving_address and total.
/api/wallet-send/ POST Money Sends amount bitcoins from the token owner's wallet to address.
/api/wallet-send-pin/ POST Money_pin Sends amount of bitcoins from the token owner's wallet to address, requires PIN.
/api/wallet-addr/ GET Read Gets the latest unused receiving address for the token owner's wallet.

Invoices

Requires Authentication Endpoint HTTP method Permissions Function
/api/merchant/invoices/ GET Read Lists all invoices created.
/api/merchant/new_invoice/ POST Read Create a new invoice.
/api/merchant/invoice/{invoice_id}/ GET Read Returns information on a specific invoice ID.
/api/merchant/delete_invoice/{invoice_id}/ POST Read, Write Deletes a specific invoice ID.

Public Market Data

Requires Authentication Endpoint HTTP method Permissions Function
/buy-bitcoins-with-cash/{location_id}/{location_slug}/.json - - Returns local buy advertisements.
/sell-bitcoins-for-cash/{location_id}/{location_slug}/.json - - Returns local sell advertisements.
/buy-bitcoins-online/{countrycode:2}/{country_name}/{payment_method}/.json - -
/buy-bitcoins-online/{countrycode:2}/{country_name}/.json - -
/buy-bitcoins-online/{currency:3}/{payment_method}/.json - -
/buy-bitcoins-online/{currency:3}/.json - -
/buy-bitcoins-online/{payment_method}/.json - -
/buy-bitcoins-online/.json - -
/sell-bitcoins-online/{countrycode:2}/{country_name}/{payment_method}/.json - -
/sell-bitcoins-online/{countrycode:2}/{country_name}/.json - -
/sell-bitcoins-online/{currency:3}/{payment_method}/.json - -
/sell-bitcoins-online/{currency:3}/.json - -
/sell-bitcoins-online/{payment_method}/.json - -
/sell-bitcoins-online/.json - -
/bitcoinaverage/ticker-all-currencies/ - - Returns a JSON feed of average Bitcoin prices on LocalBitcoins for all currencies.
/bitcoincharts/{currency}/trades.json - - Returns a list of completed trades with amount and FIAT price.
/bitcoincharts/{currency}/orderbook.json - - Returns a list of online buy and sell advertisements.

/api/account_info/{username}/

Required arguments -
Optional arguments -
Permissions Read
HTTP method GET

Description

This API request lets you retrieve the public user information on a LocalBitcoins user. The response contains the same information that is found on an account's public profile page.

Making this request with authentication returns extra information.

If you have left feedback to the account you've requested the field my_feedback will have one of the following string values: trust, positive, neutral, block, block_without_feedback.

If you have also set a feedback message for the user, it can be found from field my_feedback_msg.

Example output

                {
                  "data": {
                     "username": "bitcoinbaron",
                     "created_at": "2013-06-25T14:11:30+00:00",
                     "trading_partners_count": 0,
                     "feedbacks_unconfirmed_count": 0,
                     "trade_volume_text": "Less than 25 BTC",
                     "has_common_trades": false,
                     "confirmed_trade_count_text": "0",
                     "blocked_count": 0,
                     "feedback_score": 0,
                     "feedback_count": 0,
                     "url": "https://localbitcoins.com/p/bitcoinbaron/",
                     "trusted_count": 0,
                     "identity_verified_at": null or date,
                     "real_name_verifications_trusted": 1,
                     "real_name_verifications_untrusted": 4,
                     "real_name_verifications_rejected": 0
                   }
                }
              

/api/ads/

Argument Type Values
Required arguments -
Optional arguments visible Boolean 0 for false, 1 for true.
trade_type String One of LOCAL_SELL, LOCAL_BUY, ONLINE_SELL, ONLINE_BUY
currency String Three letter currency code. See list of valid currencies
countrycode String Two letter country code. See valid country codes
       
Permissions Read
HTTP method GET

Description

Returns the token owner's all advertisements in the data key ad_list. If there are a lot of ads, the response will be paginated. You can filter the response using the optional arguments.

Example response

                {
                    "data": {
                        "visible": boolean,
                        "hidden_by_opening_hours": boolean,
                        "location_string": human-readable location identifier string,
                        "countrycode": countrycode string, two letters,
                        "city": city name,
                        "trade_type": string, often one of LOCAL_SELL, LOCAL_BUY, ONLINE_SELL, ONLINE_BUY,
                        "online_provider": payment method string e.g. NATIONAL_BANK,
                        "first_time_limit_btc": string representation of a decimal or null,
                        "volume_coefficient_btc": string repr of a decimal,
                        "sms_verification_required": boolean
                        "reference_type": string, e.g. SHORT,
                        "display_reference": boolean,
                        "currency": three letter string,
                        "lat": float,
                        "lon": float,
                        "min_amount": string repr of a decimal or null,
                        "max_amount": string repr of a decimal or null,
                        "max_amount_available": string repr of a decimal or null,
                        "limit_to_fiat_amounts": "5,10,20",
                        "ad_id": primary key of the ad,
                        "temp_price_usd": current price per BTC in USD,
                        "floating": boolean if LOCAL_SELL,
                        "profile": null or {
                            "username": advertisement owner's profile username,
                            "name": username, trade count and feedback score combined,
                            "last_online": user last seen, ISO formatted date,
                            "trade_count": number of trades for user,
                            "feedback_score": int
                        }
                        "require_feedback_score": 50,
                        "require_trade_volume": null,
                        "require_trusted_by_advertiser": boolean,
                        "payment_window_minutes": 30,
                        "bank_name": string,
                        "track_max_amount": boolean,
                        "atm_model": string or null
                    },
                    "actions": {
                        "public_view": URL to view this ad's public HTML page
                    }
                }

If the advertisement's owner is the same user as the token owner, there are more fields in addition to the above:

                {
                    "data": {
                        ...
                        "price_equation": string,
                        "opening_hours": "null" or "[[sun_start, sun_end], [mon_start, mon_end], [tue_start, tue_end], [wed_start, wed_end], [thu_start, thu_end], [fri_start, fri_end], [sat_start, sat_end]",
                        "account_info": string,
                        "account_details": {
                            payment method specific fields
                        }
                    },
                    "actions": {
                        ...
                        "html_edit": URL to view this ad's HTML edit page
                                     that has more options than the API change_form does
                        "change_form": URL to change this ad
                    }
                }

If the token owner can create a trade with the advertisement, the contact form URL is also returned.

                {
                    ...
                    "actions": { "contact_form": URL to contact form API for this ad }
                }

Note that ATM advertisements are also returned by the API. Contacts cannot be created to ATM advertisements if the contact_form action is missing.

For ONLINE_BUY advertisements a is_low_risk boolean is returned. If this is set TRUE, the ad has displays a green thumb on the website.

min_amount and max_amount are in denominated in currency.

track_max_amount is the same as the advertisement option "Track liquidity" on web site.

/api/ad-get/{ad_id}/

Required arguments -
Optional arguments -
Permissions Read
HTTP method GET

Description

Returns information of single advertisement based on the ad ID, it returns the same fields as /api/ads/.

If a valid advertisement ID is provided the API response returns the ad within a list structure. If the advertisement is not viewable an error is returned.

/api/ad-get/

Argument Type Values
Required arguments ads String Comma separated list of advertisement IDs.
Optional arguments -
       
Permissions Read
HTTP method GET

Description

Returns all advertisements from a comma-separated list of ad IDs. Invalid advertisement ID's are ignored and no error is returned. Otherwise it functions the same as /api/ad-get/{ad_id}/.

A maximum of 50 advertisements are returned at a time.

Advertisements are not returned in any particular order.

/api/ad/{ad_id}/ Editing

Argument Type Values
Required arguments price_equation String Price equation formula
lat Integer Latitude coordinate
lon Integer Longitude coordinate
city String City name
location_string String Human readable location text.
countrycode String Two-character country code. See valid country codes
currency String Three letter currency code. See list of valid currencies. With ONLINE_SELL and ONLINE_BUY ads, some payment methods might limit the allowed currencies. Altcoin currencies are only allowed with ONLINE_SELL and ONLINE_BUY ads, if they are included in the currency list of payment method.
account_info String -
bank_name String Certain of the online payment methods require bank_name to be chosen from a limited set of names. To find out these limited choices, use this public API request /api/payment_methods/
msg String Terms of trade of the advertisement
sms_verification_required Boolean 0 for false, 1 for true.
track_max_amount Boolean 0 for false, 1 for true.
require_trusted_by_advertiser Boolean 0 for false, 1 for true.
require_identification Boolean 0 for false, 1 for true.
Optional arguments min_amount Integer Minimum transaction limit in fiat.
max_amount Integer Maximum transaction limit in fiat.
opening_hours JSON array Times when ad is visible (Set according to timezone set with token owners account).
limit_to_fiat_amounts String Comma separated fiat value list of amounts to restrict. Same as "Restrict amounts to" on site.
visible Boolean 0 for false, 1 for true.
Optional arguments ONLINE_SELL ads require_trade_volume Integer -
require_feedback_score Integer -
first_time_limit_btc Integer -
volume_coefficient_btc Integer -
reference_type String Supported values are SHORT, LONG, NUMBERS, LETTERS
display_reference Boolean Show reference in trades opened using this ad. 0 for false, 1 for true.
Optional arguments ONLINE_BUY payment_window_minutes Integer Payment window time in minutes.
Optional arguments LOCAL_SELL floating Boolean Enable floating price for the ad. 0 for false, 1 for true.
       
Permissions -
HTTP method POST

Description

Sending a request to /api/ad/{ad_id}/ with the HTTP method POST for an advertisement ID that was created by the token owner results in the advertisement being updated.

NOTE Omitting optional requirements, such as min_amount, max_amount or opening_hours, will unset them. You may want to pass through all fields from the /api/ads/ records you're editing. Fields require_trade_volume, require_feedback_score, first_time_limit_btc, volume_coefficient_btc, payment_window_minutes, reference_type, display_reference and limit_to_fiat_amounts are not cleared if they are omitted.

Errors in the new values are reported in the errors key. If there are any errors, no changes will be made to the ad.

This API endpoint functions the same as /api/ad-create/ apart from the addition of the argument visible that allows you to turn the advertisement visibility on and off. Please see /api/ad-create/ for further information on the arguments for this API endpoint.

/api/ad-create/ Creation

Argument Type Values
Required arguments price_equation String Price equation formula
lat Integer Latitude coordinate
lon Integer Longitude coordinate
city String City name
location_string String Human readable location text.
countrycode String Two-character country code. See valid country codes
currency String Three letter currency code. See list of valid currencies. With ONLINE_SELL and ONLINE_BUY ads, some payment methods might limit the allowed currencies. Altcoin currencies are only allowed with ONLINE_SELL and ONLINE_BUY ads, if they are included in the currency list of payment method.
account_info String -
bank_name String Certain online payment methods require bank_name to be chosen from a limited set of names. To find out these limited choices, use /api/payment_methods/
msg String Terms of trade of the advertisement.
sms_verification_required Boolean 0 for false, 1 for true.
track_max_amount Boolean 0 for false, 1 for true.
require_trusted_by_advertiser Boolean 0 for false, 1 for true.
require_identification Boolean 0 for false, 1 for true.
online_provider String You can find a list of valid payment method at /api/payment_methods/
trade_type String ONLINE_BUY, ONLINE_SELL, LOCAL_SELL, LOCAL_BUY
Optional arguments min_amount Integer Minimum transaction limit in fiat.
max_amount Integer Maximum transaction limit in fiat.
opening_hours JSON array Times when ad is visible (Set according to timezone set with token owners account).
limit_to_fiat_amounts String Comma separated fiat value list of amounts to restrict. Same as "Restrict amounts to" on site.
visible Boolean 0 for false, 1 for true.
Optional arguments ONLINE_SELL ads require_trade_volume Integer -
require_feedback_score Integer -
first_time_limit_btc Integer -
volume_coefficient_btc Integer -
reference_type String Supported values are SHORT, LONG, NUMBERS, LETTERS
display_reference Boolean Show reference in trades opened using this ad. 0 for false, 1 for true.
Optional arguments ONLINE_BUY payment_window_minutes Integer Payment window time in minutes.
Optional arguments LOCAL_SELL floating Boolean Enable floating price for the ad. 0 for false, 1 for true.
       
Permissions -
HTTP method POST

Description

This API endpoint is for creating new advertisements for the token owner. Only fields listed above can be used with the API, use the web site to change the rest of them.

opening_hours is given as JSON array in the same format as it is returned when getting details of ads. Weekdays start from Sunday and each weekday contains start and end that are measured as 15 minutes. So for example 4 means 01:00 and 5 means 01:15.

Some of the online payment methods require bank_name to be chosen from a limited set of names. To find out these limited choices, use this public API request /api/payment_methods/. They can be found from the key bank_name_choices.

ONLINE_SELL advertisements may have additional fields you need to provide, depending on the advertisement's payment method (online_provider).

Local Advertisements

Creating Local advertisements functions the same as online advertisements but with a couple of differences:

  • Local ads have a distance field on each ad, supplied in kilometers.
  • Local ads are not paginated. You can, however, look up ads from other nearby locations as a workaround.

/api/ad-delete/{ad_id}/

Required arguments -
Optional arguments -
Permissions Read, Write
HTTP method POST

Description

Sending a request to this endpoint with an advertisement ID created by the token owner deletes the advertisement.

/api/contact_release/{contact_id}/

Argument Type Values
Required arguments contact_id Integer Trade ID number.
Optional arguments -
       
Permissions Money
HTTP method POST

Description

Releases Bitcoin trades specified by ID {contact_id}. If the release was successful a message is returned on the data key.

/api/contact_release_pin/{contact_id}/

Argument Type Values
Required arguments pincode Integer User Apps PIN code.
Optional arguments -
       
Permissions Money_pin
HTTP method POST
Permissions Money_pin
HTTP method POST

Description

Releases Bitcoin trades specified by ID {contact_id}. if the current pincode is provided. If the release was successful a message is returned on the data key.

/api/contact_mark_as_paid/{contact_id}/

Required arguments -
Optional arguments -
   
Permissions Read, Write
HTTP method POST

Description

Marks a trade as paid.

/api/contact_messages/{contact_id}/

Required arguments -
Optional arguments -
Permissions Read
HTTP method GET

Description

Returns all chat messages from the trade. Messages are on the message_list key. The structure of a message is as follows:

              {
                  "msg": "message body",
                  "sender": {
                      "id": 123,
                      "name": "bitcoinbaron (0)",
                      "username": "bitcoinbaron",
                      "trade_count": 0,
                      "last_online": "2013-12-17T03:31:12.382862+00:00"
                  },
                  "created_at": "2013-12-19T16:03:38.218039",
                  "is_admin": false,
                  "attachment_name": "cnXvo5sV6eH4-some_image.jpg",
                  "attachment_type": "image/jpeg",
                  "attachment_url": "https://localbitcoins.com/api/..."
              }
            

attachment_* fields exist only if there is an attachment.

/api/contact_message_post/{contact_id}/

Argument Type Values
Required arguments
one or both
msg String Chat message to trade chat.
document File Image attachments encoded with multipart/form-data
Optional arguments -
       
Permissions Read, Write
HTTP method POST

Description

Posts a message and/or uploads an image to the trade. Encode images with multipart/form-data encoding.

/api/contact_dispute/{contact_id}/

Argument Type Values
Required arguments -
Optional arguments topic String Short description of issue to LocalBitcoins customer support.
       
Permissions Read, Write
HTTP method POST

Description

Starts a dispute on the specified trade ID if the requirements for starting the dispute has been fulfilled. See the FAQ for up-to-date details regarding dispute requirements.

You can provide a short (optional) description using topic. This helps customer support to deal with the problem.

/api/contact_cancel/{contact_id}/

Required arguments -
Optional arguments -
Permissions Read, Write
HTTP method POST

Description

Cancels the trade if the token owner is the Bitcoin buyer. Bitcoin sellers cannot cancel trades.

/api/contact_fund/{contact_id}

Required arguments -
Optional arguments -
Permissions Read, Write
HTTP method POST

Description

Attempts to fund an unfunded local trade from the token owners wallet. Works only if the token owner is the Bitcoin seller in the trade.

/api/contact_mark_realname/{contact_id}/

Argument Type Values
Required arguments confirmation_status Integer 1 = Name matches
2 = Name was different
3 = Name was not checked
4 = Name was not visible
id_confirmed Boolean 0 for false, 1 for true.
Optional arguments -
   
Permissions Read, Write
HTTP method POST

Description

Creates or updates real name confirmation.

/api/contact_mark_identified/{contact_id}/

Required arguments -
Optional arguments -
Permissions Read, Write
HTTP method POST

Description

Marks the identity of trade partner as verified. You must be the advertiser in this trade.

/api/contact_create/{ad_id}/

Argument Type Values
Required arguments amount Integer Number in the advertisement's fiat currency.
Optional arguments message String Optional message to send to the advertiser.
       
Permissions Read, Write
HTTP method POST

Description

Attempts to start a Bitcoin trade from the specified advertisement ID.

Amount is a number in the advertisement's fiat currency.

Returns the API URL to the newly created contact at actions.contact_url. Whether the contact was able to be funded automatically is indicated at data.funded. Only non-floating LOCAL_SELL may return unfunded, all other trade types either fund or fail.

ONLINE_BUY advertisements may have additional fields you need to provide depending on the advertisement's payment method (online_provider).

/api/contact_info/{contact_id}/

Required arguments -
Optional arguments -
Permissions Read
HTTP method GET

Description

Returns information about a single trade that the token owner is part in.

/api/contact_info/

Argument Type Values
Required arguments contacts - CSV list of trade ID numbers.
Optional arguments -
       
Permissions Read
HTTP method GET

Description

contacts is a comma-separated list of contact IDs that you want to access in bulk. The token owner needs to be either a buyer or seller in the contacts, contacts that do not pass this check are simply not returned.

A maximum of 50 contacts can be requested at a time.

The contacts are not returned in any particular order.

/api/countrycodes/

Required arguments -
Optional arguments -
Permissions -
HTTP method GET

Description

List of valid and recognized countrycodes for LocalBitcoins.com. Return value is structured like so:

            {
            "data": {
                "cc_list": ["fi", "fr", "us", ...],
                "cc_count": 50
                    }
            }

/api/currencies/

Required arguments -
Optional arguments -
Permissions -
HTTP method GET

Description

List of valid and recognized fiat currencies for LocalBitcoins.com. Also contains human readable name for every currency and boolean that tells if currency is an altcoin.

/api/dashboard/

Required arguments -
Optional arguments -
Permissions Read
HTTP method GET

Description

Returns a list of trades on the data key contact_list. This API end point mirrors the website's dashboard, allowing access to contacts in different states.

In addition all of these listings have buyer/ and seller/ sub-listings to view contacts where the token owner is either buying or selling, respectively. E.g. /api/dashboard/buyer/. All contacts where the token owner is participating are returned.

Structure of common values to all contacts is follows:

              {
                "data": {
                  "created_at": "2013-12-06T15:23:01.61",
                  "buyer": {
                      "username": "hylje",
                      "trade_count": "30+",
                      "feedback_score": "100",
                      "name": "hylje (30+; 100)",
                      "last_online": "2013-12-19T08:28:16+00:00",
                      "real_name": string or null if ONLINE trade where you are the seller,
                      "company_name": string or null if ONLINE trade where you are the seller,
                      "countrycode_by_ip": string or null if ONLINE trade where you are the seller,
                      "countrycode_by_phone_number": string or null if ONLINE trade where you are the seller
                  }
                  "seller": {
                      "username": "jeremias",
                      "trade_count": "100+",
                      "feedback_score": "100",
                      "name": "jeremias (100+; 100)",
                      "last_online": "2013-12-19T06:28:51+00:00"
                  }
                  "reference_code": "123",
                  "currency": "EUR",
                  "amount": "105.55",
                  "amount_btc": "190",
                  "fee_btc": "1.9",
                  "exchange_rate_updated_at": "2013-06-20T15:23:01+00:00",
                  "advertisement": {
                     "id": 123,
                     "trade_type": "ONLINE_SELL"
                     "advertiser": {
                         "username": "jeremias",
                         "trade_count": "100+",
                         "feedback_score": "100",
                         "name": "jeremias (100+; 100)",
                         "last_online": "2013-12-19T06:28:51.604754+00:00"
                     }
                  },
                  "contact_id": 1234
                  "canceled_at": null,
                  "escrowed_at": "2013-12-06T15:23:01+00:00",
                  "funded_at": "2013-12-06T15:23:01+00:00",
                  "payment_completed_at": "2013-12-06T15:23:01+00:00",
                  "disputed_at": null,
                  "closed_at": null,
                  "released_at": null,
                  "is_buying": true,
                  "is_selling": false,
                  "account_details": ! see below,
                  "account_info": Payment details of ONLINE_SELL as string, if account_details is missing.,
                  "floating": boolean if LOCAL_SELL
                },
                "actions": {
                  "mark_as_paid_url": "/api/contact_mark_as_paid/1/",
                  "advertisement_public_view": "/ads/123",
                  "message_url": "/api/contact_messages/1234",
                  "message_post_url": "/api/contact_message_post/1234"
                }
              }
            

Notes on common fields

The created_at field is an ISO formatted UTC datetime.

The amount (denominated in currency) and amount_btc fields are string representations of Decimals, both set at the time of creation of the escrow. The exchange rate between the two fields was last looked up at exchange_rate_updated_at.

is_buying and is_selling are shortcuts that indicate that the token owner is the buyer or seller in this contact.

canceled_at, escrowed_at, funded_at, disputed_at, closed_at and released_at are all either datetimes or null, reflecting the progress of the contact along the trade. Once a trade enters a state (a datetime is set) it will never unset the state.

Extra fields by trade type / user role

Trade type(s) Buyer/seller Key path About
Online sell and online buy Buyer and seller data.advertisement.payment_method Online payment method. See /api/payment_methods/ for up-to-date options. E.g. SEPA
Online buy Buyer and seller data.account_details
                    {
                      "receiver_name": "John Doe",
                      "iban": iban account number
                      "swift_bic": bank identification code
                      "reference": "789"
                    }
                  

See more on the Account Details heading below.

Online buy Buyer only actions.mark_as_paid_url URL to API that marks this contact as paid.
All contacts with escrow enabled and funded Seller only actions.release_url URL to API that releases this contact's escrow
All contacts with escrow enabled but not funded Seller only actions.fund_url URL to API that attempts to fund this contact's escrow
Buyer and seller data.is_funded

Boolean signalling if the escrow is enabled and not funded.

Note: If escrow is not enabled, this value is unset.

Conditional fields for all contacts

In all contacts, actions key may also have dispute_url available if the contact is eligible for dispute. Or a cancel_url if the contact is eligible for canceling.

About account_details

account_details contains a payment method specific set of payment information supplied by the seller.

See the current list of payment details information supported on LocalBitcoins

Pagination

All dashboard contact listings paginate. See the section on pagination.

/api/dashboard/released/

Required arguments -
Optional arguments -
Permissions Read
HTTP method GET

Description

Returns a list of all released trades where the token owner is either a buyer or seller. See /api/dashboard/ for more information.

/api/dashboard/canceled/

Required arguments -
Optional arguments -
Permissions Read
HTTP method GET

Description

Returns a list of all canceled trades where the token owner is either a buyer or seller. See /api/dashboard/ for more information.

/api/dashboard/closed/

Required arguments -
Optional arguments -
Permissions Read
HTTP method GET

Description

Returns a list of all closed trades where the token owner is either a buyer or seller. See /api/dashboard/ for more information.

/api/feedback/{username}/

Argument Type Values
Required arguments feedback String Allowed values are: trust, positive, neutral, block, block_without_feedback.
Optional arguments msg String Feedback message displayed alongside feedback on receivers profile page.
       
Permissions Read, Write
HTTP method POST

Description

Gives feedback to user. Possible feedback values are: trust, positive, neutral, block, block_without_feedback.

This is only possible to set if there is a trade between the token owner and the user specified in {username} that is canceled or released.

You may also set feedback message using msg field with few exceptions. Feedback block_without_feedback clears the message and with block the message is mandatory.

/api/logout/

Required arguments -
Optional arguments -
Permissions Read
HTTP method POST

Description

Expires the current access token immediately. To get a new token afterwards, public apps will need to re-authenticate, confidential apps can turn in a refresh token.

/api/merchant/invoices/

Required arguments -
Optional arguments -
Permissions Read
HTTP method GET

Description

Lists all invoices. If there are a lot of invoices, the listing will be paginated. Data structure is described below. invoice_list contains objects that are identical to those in API request /api/merchant/invoice/{invoice_id}/.

              {
                  "data": {
                      "invoice_list": ...
                  },
                  "pagination": {
                     "next": "https://localbitcoins.com/api/invoices/?..."
                  }
              }
            

/api/merchant/new_invoice/

Argument Type Values
Required arguments currency String Three letter currency code. See list of valid currencies
amount Integer The Bitcoin amount of the invoice
description String
Optional arguments return_url String URL to automatically redirect customers to after invoice is paid.
       
Permissions Read
HTTP method POST

Description

Creates a new invoice. currency is a three letter currency code, for example USD. Please see a list of all valid currencies. For more information how invoices work, check Merchant dashboard. You can check response structure from API request /api/merchant/invoice/{invoice_id}/

After invoice has been created, you need to deliver its URL to your customer or redirect him/her to it.

You can use return_url to redirect customers automatically back to your site. Redirection happens after the invoice has been paid.

If redirecting fails, the customer can also click the return link manually. Make sure it does not cause problems if the return_url is visited multiple times.

Also note, that return_url is not guaranteed to stay secret from the customer, so do not consider the invoice been paid when the URL is being visited.

Instead use the API request /api/merchant/invoice/{invoice_id}/ to check payment status.

/api/merchant/invoice/{invoice_id}/

Required arguments -
Optional arguments -
Permissions READ
HTTP method GET

Description

Returns information about a specific invoice created by the token owner. Example result can be seen below:

              {
                  "data": {
                      "invoice": {
                          "description": "Stuff",
                          "created": "2014-09-11T09:34:30.867980",
                          "url": "https://localbitcoins.com/merchant/invoice/VD1j3VP7MSjTJjxaptjnFN",
                          "amount": "4.99",
                          "currency": "EUR",
                          "state": "NOT_OPENED",
                          "id": "VD1j3VP7MSjTJjxaptjnFN",
                          "btc_amount": null,
                          "btc_address": null,
                          "deleting_allowed": true
                      }
                  }
              }
            

State is one of these: NOT_OPENED, WAITING_FOR_PAYMENT, PAID, DIDNT_PAID, PAID_IN_LATE, PAID_PARTLY, PAID_AND_CONFIRMED, PAID_IN_LATE_AND_CONFIRMED, PAID_PARTLY_AND_CONFIRMED.

/api/merchant/delete_invoice/{invoice_id}/

Required arguments -
Optional arguments -
Permissions Read, Write
HTTP method POST

Description

Deletes a specific invoice. Deleting invoices is possible when it is sure that receiver cannot accidentally pay the invoice at the same time as the merchant is deleting it. You can use the API request /api/merchant/invoice/{invoice_id}/ to check if deleting is possible.

/api/myself/

Required arguments -
Optional arguments -
Permissions Read
HTTP method GET

Description

Returns information of the currently logged in user (the owner of authentication token). The format is the same as in /api/account_info/{username}.

              {
                "data": {
                   "username": "bitcoinbaron",
                   "created_at": "2013-06-25T14:11:30+00:00",
                   "trading_partners_count": 0,
                   "feedbacks_unconfirmed_count": 0,
                   "trade_volume_text": "Less than 25 BTC",
                   "has_common_trades": false,
                   "confirmed_trade_count_text": "0",
                   "blocked_count": 0,
                   "feedback_score": 0,
                   "feedback_count": 0,
                   "url": "https://localbitcoins.com/p/bitcoinbaron/",
                   "trusted_count": 0,
                   "identity_verified_at": null or date,
                   "real_name_verifications_trusted": 1,
                   "real_name_verifications_untrusted": 4,
                   "real_name_verifications_rejected": 0
                 }
              }
            

/api/notifications/

Required arguments -
Optional arguments -
Permissions Read
HTTP method GET

Description

Returns recent notifications. Example result can be seen below:

              {
                  "data": [
                      {
                          "url": "/request/online_sell_seller/7126534",
                          "created_at": "2016-10-19T13:42:42+00:00",
                          "contact_id": 7126534,
                          "read": false,
                          "msg": "You have a new offer #7126534!",
                          "id": "fc431e381909"
                      },
                      {
                          "url": "/ads_edit/323473",
                          "created_at": "2016-10-19T13:42:42+00:00",
                          "advertisement_id": 323473,
                          "read": false,
                          "msg": "Your ad has been hidden because Track Liquidity reached the minimum amount. Change the setting or increase the ad's max amount.",
                          "id": "469912a4e83a"
                      }
                  ]
              }
            

/api/notifications/mark_as_read/{notification_id}/

Required arguments -
Optional arguments -
Permissions Read, Write
HTTP method POST

Description

Marks a specific notification as read.

/api/payment_methods/

Required arguments -
Optional arguments -
Permissions -
HTTP method GET

Description

Returns a list of valid payment methods. Also contains name and code for payment methods, and possible limitations in currencies and bank name choices.

/api/payment_methods/{countrycode}/

Required arguments -
Optional arguments -
Permissions -
HTTP method GET

Description

Returns a list of valid payment methods filtered by countrycodes. Also contains name and code for payment methods, and possible limitations in currencies and bank name choices.

/api/pincode/

Argument Type Values
Required arguments pincode Integer 4 digit app PIN code set from profile settings
Optional arguments -
       
Permissions Read
HTTP method POST

Description

Checks the given PIN code against the token owners currently active PIN code. You can use this method to ensure the person using the session is the legitimate user.

Due to only requiring the read scope, the user is not guaranteed to have set a PIN code. If you protect your application using this request, please make the user has set a PIN code for his account.

/api/places/

Argument Type Values
lat Integer Latitude coordinate
lon Integer Longitude coordinate
Optional arguments countrycode String Two-character country code. See valid country codes
location_string String Human readable location text.
       
Permissions -
HTTP method GET

Description

Looks up places near lat, lon and provides full URLs to buy and sell listings for each.

You can use external services like Google Places to find lat/lon coordinates for addresses and the like. That way you can also get countrycode and location_string values to improve your lookup.

An InvalidParameter (error code 11) is returned if the parameters did not seem valid.

/api/real_name_verifiers/{username}/

Argument Type Values
Required arguments -
Optional arguments -
       
Permissions Read
HTTP method GET

Returns list of real name verifiers for the user. Returns a list only when you have a trade with the user where you are the seller.

[{"username": "henu.tester", "verified_at": "2016-10-13T13:49:45+00:00"}]

/api/recent_messages/

Argument Type Values
Required arguments -
Optional arguments after Date Return messages before date. UTC date in ISO 8601 format
       
Permissions Read
HTTP method GET

Description

Returns maximum of 25 newest trade messages. Does not return messages older than one month. Messages are ordered by sending time, and the newest one is first. The list has same format as /api/contact_messages/, but each message has also contact_id field.

If you would like to see messages after a specific date, use the parameter after. It takes UTC date in ISO 8601 format. Only messages that are sent after the date are listed. This is useful if you are polling the call repeatedly and want to avoid receiving the same messages again.

Transaction types

Transactions in the Wallet API have several types. Currently the more elaborate types cover sends. All received transactions are of type 3.

Type Summary Extra fields
1 Send to_address: the recipient Bitcoin address
2 Pending Send. The transaction processor has not yet published a transaction containing this send to the Bitcoin network, but will do so as quickly as possible. to_address: the to-be-recipient Bitcoin address
3 Other transactions, e.g. received transactions. See the description field.
4 Bitcoin network fees
5 Internal send to another LocalBitcoins wallet

/api/wallet/

Required arguments -
Optional arguments -
Permissions Read
HTTP method GET

Description

Gets information about the token owner's wallet balance. The information is as follows:

              {
                "message": "OK",
                "total": {
                  "balance": "0.05",
                  "sendable": "0.05"
                },
                "sent_transactions_30d": [
                  {"txid": ...
                   "amount": "0.05",
                   "description": "Internal send",
                   "tx_type": 5,
                   "created_at": "2013-12-20T15:27:36+00:00"
                }
                ],
                "received_transactions_30d": [...],
                "receiving_address": "1CsgXvijdeFr47JfATYgV7XzUrrAAsds12",
                "old_address_list": [{
                  "address": "15HfUY9Lw...",
                  "received": "0.0"
                }]
              }
            

The transaction lists are for the last 30 days. There is no LocalBitcoins API to fetch older transactions than that. Returns max 10 old addresses. The old addresses are truncated, because they are not meant to be used. If the account is new, the receiving_address might be null. In this case you can create a new address with /api/wallet-addr/.

/api/wallet-balance/

Required arguments -
Optional arguments -
Permissions Read
HTTP method GET

Description

Same as /api/wallet/ above, but only returns the message, receiving_address and total fields.

Use this instead if you don't care about transactions at the moment.

/api/wallet-send/

Argument Type Values
Required arguments address String Bitcoin address where you're sending Bitcoin to.
amount Integer Amount of Bitcoin to send.
Optional arguments -
       
Permissions Money
HTTP method POST

Description

Sends amount of bitcoins from the token owner's wallet to address.

On success, the response returns a message indicating success.

It is highly recommended to minimize the lifetime of access tokens with the money permission. Request /api/logout/ to make the current token expire instantly.

/api/wallet-send-pin/

Argument Type Values
Required arguments address String Bitcoin address where you're sending Bitcoin to.
amount Integer Amount of Bitcoin to send.
pincode Integer Token owners PIN code. See /api/pincode/.
Optional arguments -
       
Permissions Money_PIN
HTTP method POST

Description

As /api/wallet-send/, but needs the token owner's active PIN code to succeed.

You can check if a PIN code is valid with the API request /api/pincode/.

Security concern: To improve security, do not save the PIN code longer than the users session, a few minutes at most. If you are planning to save the PIN code please use the money permission instead.

/api/wallet-addr/

Required arguments -
Optional arguments -
Permissions Read
HTTP method POST

Description

Returns an unused receiving address from the token owner's wallet. The address is returned in the address key of the response. Note that this API may keep returning the same (unused) address if requested repeatedly.

/buy-bitcoins-with-cash/{location_id}/{location_slug}/.json

Required arguments -
Optional arguments -
Permissions -
HTTP method -

Description

This endpoint returns local advertisements. You can give lat and lon - parameters to specify a location near {location_id}, up to 50 kilometers away.

The following API is useful to - the {location_id} and {location_slug} for a lat/lon.

/sell-bitcoins-for-cash/{location_id}/{location_slug}/.json

Required arguments -
Optional arguments -
Permissions -
HTTP method -

Description

This endpoint looks up local ads. You can give lat and lon - parameters to specify a location near {location_id}, up to 50 kilometers away.

The following API is useful to - the {location_id} and {location_slug} for a lat/lon.

/buy-bitcoins-online/{countrycode:2}/{country_name}/{payment_method}/.json

Required arguments -
Optional arguments -
Permissions -
HTTP method -

Description

This API returns buy Bitcoin online ads. It is closely modeled after the online ad listings on LocalBitcoins.com. It occupies the same URLs with .json appended.

Countrycodes are always exactly two characters. Currencies are always exactly three characters. Anything longer than that is a payment method. country_name is the full name of the country with _ instead of spaces.

An example of a valid payment_method argument is national-bank-transfer. See /api/payment_methods/ for a list of all valid payment methods.

Ads are returned in the same structure as /api/ads/.

/buy-bitcoins-online/{countrycode:2}/{country_name}/.json

Required arguments -
Optional arguments -
Permissions -
HTTP method -

Description

This API returns buy Bitcoin online ads. It is closely modeled after the online ad listings on LocalBitcoins.com. It occupies the same URLs with .json appended.

countrycode is exactly two characters. country_name is the full name of the country with _ instead of spaces.

Ads are returned in the same structure as /api/ads/.

/buy-bitcoins-online/{currency:3}/{payment_method}/.json

Required arguments -
Optional arguments -
Permissions -
HTTP method -

Description

This API returns buy Bitcoin online ads. It is closely modeled after the online ad listings on LocalBitcoins.com. It occupies the same URLs with .json appended.

Currencies are always exactly three characters. Anything longer than that is a payment method.

An example of a valid payment_method argument is national-bank-transfer. See /api/payment_methods/ for a list of all valid payment methods.

Ads are returned in the same structure as /api/ads/.

/buy-bitcoins-online/{currency:3}/.json

Required arguments -
Optional arguments -
Permissions -
HTTP method -

Description

This API returns buy Bitcoin online ads. It is closely modeled after the online ad listings on LocalBitcoins.com. It occupies the same URLs with .json appended.

Currencies are always exactly three characters. Anything longer than that is a payment method.

Ads are returned in the same structure as /api/ads/.

/buy-bitcoins-online/{payment_method}/.json

Required arguments -
Optional arguments -
Permissions -
HTTP method -

Description

This API look up buy Bitcoin online ads. It is closely modeled after the online ad listings on LocalBitcoins.com. It occupies the same URLs with .json appended.

An example of a valid payment_method argument is national-bank-transfer. See /api/payment_methods/ for a list of all valid payment methods.

Ads are returned in the same structure as /api/ads/.

/buy-bitcoins-online/.json

Required arguments -
Optional arguments -
Permissions -
HTTP method -

Description

This API returns buy Bitcoin online ads. It is closely modeled after the online ad listings on LocalBitcoins.com. It occupies the same URLs with .json appended. Ads are returned in the same structure as /api/ads/.

An example of a valid payment_method argument is national-bank-transfer. See /api/payment_methods/ for a list of all valid payment methods.

Ads are returned in the same structure as /api/ads/.

/buy-bitcoins-online/.json

Required arguments -
Optional arguments -
Permissions -
HTTP method -

Description

This API returns buy Bitcoin online ads. It is closely modeled after the online ad listings on LocalBitcoins.com. It occupies the same URLs with .json appended.

Ads are returned in the same structure as /api/ads/.

/sell-bitcoins-online/{countrycode:2}/{country_name}/.json

Required arguments -
Optional arguments -
Permissions -
HTTP method -

Description

This API look up sell Bitcoin online ads. It is closely modeled after the online ad listings on LocalBitcoins.com. It occupies the same URLs with .json appended.

Countrycodes are always exactly two characters. Currencies are always exactly three characters. Anything longer than that is a payment method. country_name is the full name of the country with _ instead of spaces.

Ads are returned in the same structure as /api/ads/.

/sell-bitcoins-online/{countrycode:2}/{country_name}/{payment_method}/.json

Required arguments -
Optional arguments -
Permissions -
HTTP method -

Description

This API returns sell Bitcoin online ads. It is closely modeled after the online ad listings on LocalBitcoins.com. It occupies the same URLs with .json appended.

Countrycodes are always exactly two characters. Currencies are always exactly three characters. Anything longer than that is a payment method. country_name is the full name of the country with _ instead of spaces.

An example of a valid payment_method argument is national-bank-transfer. See /api/payment_methods/ for a list of all valid payment methods.

Ads are returned in the same structure as /api/ads/.

/sell-bitcoins-online/{countrycode:2}/{country_name}/.json

Required arguments -
Optional arguments -
Permissions -
HTTP method -

Description

This API returns sell Bitcoin online ads. It is closely modeled after the online ad listings on LocalBitcoins.com. It occupies the same URLs with .json appended.

Countrycodes are always exactly two characters. Currencies are always exactly three characters. Anything longer than that is a payment method. country_name is the full name of the country with _ instead of spaces.

Ads are returned in the same structure as /api/ads/.

/sell-bitcoins-online/{currency:3}/{payment_method}/.json

Required arguments -
Optional arguments -
Permissions -
HTTP method -

Description

This API returns sell Bitcoin online ads. It is closely modeled after the online ad listings on LocalBitcoins.com. It occupies the same URLs with .json appended.

Currencies are always exactly three characters. Anything longer than that is a payment method.

An example of a valid payment_method argument is national-bank-transfer. See /api/payment_methods/ for a list of all valid payment methods.

Ads are returned in the same structure as /api/ads/.

/sell-bitcoins-online/{currency:3}/.json

Required arguments -
Optional arguments -
Permissions -
HTTP method -

Description

This API returns sell Bitcoin online ads. It is closely modeled after the online ad listings on LocalBitcoins.com. It occupies the same URLs with .json appended.

Currencies are always exactly three characters. Anything longer than that is a payment method.

Ads are returned in the same structure as /api/ads/.

/sell-bitcoins-online/{payment_method}/.json

Required arguments -
Optional arguments -
Permissions -
HTTP method -

Description

This API returns sell Bitcoin online ads. It is closely modeled after the online ad listings on LocalBitcoins.com. It occupies the same URLs with .json appended.

An example of a valid payment_method argument is national-bank-transfer. See /api/payment_methods/ for a list of all valid payment methods.

Ads are returned in the same structure as /api/ads/.

/sell-bitcoins-online/.json

Required arguments -
Optional arguments -
Permissions -
HTTP method -

Description

This API returns sell Bitcoin online ads. It is closely modeled after the online ad listings on LocalBitcoins.com. It occupies the same URLs with .json appended.

Ads are returned in the same structure as /api/ads/.

/bitcoinaverage/ticker-all-currencies/

Required arguments -
Optional arguments -
Permissions -
HTTP method -

Description

This API returns a ticker-tape like list of all completed trades.

If there are no trades to calculate average for some time frame, then that average is not present.

/bitcoincharts/{currency}/trades.json

Required arguments -
Optional arguments -
Permissions -
HTTP method -

Description

All closed trades in online buy and online sell categories, updated every 15 minutes.

The maximum batch size is of a fetch is 500 entries. Use ?since= parameter with the last tid to iterate more.

/bitcoincharts/{currency}/orderbook.json

Required arguments -
Optional arguments -
Permissions -
HTTP method -

Description

Buy and sell bitcoin online advertisements. Amount is the maximum amount available for the trade request. Price is the hourly updated price. The price is based on the price equation and commission % entered by the ad author.

No batching

API error codes

Error Code Meaning Suggested action HTTP Response code
2 No OAuth 2 access token or HMAC signature was given. This resource needs one of them. Authenticate with the user to acquire an OAuth 2 access token or calculate HMAC signature from HMAC credentials HTTP 400
3 The access token given is expired or otherwise not acceptable. Reauthenticate with the user. HTTP 400
4

Resource forbidden for this token. The user can grant additional privileges to the app that allow the app to access the resource.

The missing, required scope is returned in the required_scope key.

Reauthenticate with the user with the necessary scope. HTTP 400
5 General server error. We log all errors, so if you cause an unexpected server error we'll fix it. May also happen if the service is in a degraded state. Try again in some time. HTTP 500
6 Resource not found. Don't try again. HTTP 400
7 Resource forbidden. The token owner cannot access this resource. Don't try again. HTTP 400
8 Requested action cannot be done to this object. Don't try again. HTTP 400
9

The API was called with invalid parameters.

Reasons for validation failures are given in the error_lists key. A single parameter may have multiple failures listed, which may have a common root cause.

Don't try again. HTTP 400
11

The API was called with invalid parameters.

There may be an errors key if there's a specific parameter that did not validate.

Don't try again. HTTP 400
12 The API was called with invalid HTTP method. Use proper HTTP method. HTTP 400
13 Maximum amount reached. Try again later. HTTP 400
15 The given Lat/Lon parameters were missing or invalid. Don't try again. HTTP 400
16 Countrycode was not two letters long Don't try again. HTTP 400
17 Countrycode was not in the LocalBitcoins country database Don't try again. HTTP 400
18 Send was attempted to the same wallet Don't try again. HTTP 400
19 Not enough balance to fulfill the request Don't try again. HTTP 400
20 Unspecified error with wallet. Contact LocalBitcoins support. HTTP 400
21 The contact is already paid. Don't try again. HTTP 400
22 The contact cannot be disputed at this time. It can be disputed at a later time. Don't try again. HTTP 400
23 Token owner is not the seller for this contact and cannot fund it. Don't try again. HTTP 400
24 Cannot perform requested action, because trade type is not what it should be. Don't try again. HTTP 400
26 Cannot fund the escrow as it is already funded. Don't try again. HTTP 400
27 The token owner's wallet does not have enough balance to fund the selling contact. Ask the token owner to refill the LocalBitcoins wallet HTTP 400
28

The token owner has not finalized registration yet to LocalBitcoins. The URL where he can finalize registration is given as register_url.

After a successful registration, the user is redirected back to the app callback URL. If you wish to retry using this API, you'll need to keep some session state yourself.

Don't try again. HTTP 400
29 Payment method is no longer supported. Don't try again. HTTP 400
31 The advertisement has set trading limits above what the contacter can fulfill. Doing trades on other ads may open this ad for trades. You can try repeating the trading attempt on the website to see why it failed. HTTP 400
32 The contact cannot be canceled at this time. Don't try again. HTTP 400
33 The payment method specific account details did not validate. Don't try again. HTTP 400
34 Only one of this operation is allowed to run at a time. Wait and retry if the other operation did not succeed. HTTP 400
35 This paginated API cannot be ordered with the given key. Don't try again. HTTP 400
36 This paginated API does not accept start values of this type. Don't try again. HTTP 400
37 You need to have trades with the user Make some trades with the user or use another action. HTTP 400
38 Chat is diabled at the moment for this contact and sending messages through API is not allowed. Don't try again. HTTP 400
40 Some parameter is missing. Submit all required parameters. HTTP 400
41 HMAC authentication key and signature was given, but they are invalid. Ensure validity of key, secret and signature calculation. HTTP 400
42 Given nonce was too small. Use bigger nonce. HTTP 400
43 Resource is forbidden for this HMAC authentication. Use another HMAC authentication or add more scopes to the current one. HTTP 400
44 Twofactor authentication is not enabled. Enable twofactor authentication. HTTP 400
45 The advertisement has been forced hidden because of too big price changes. Wait 10 minutes before trying again. HTTP 400
46 Identity of the account is not verified Verify your identity. HTTP 400