With the LocalBitcoins API you can query our public trade data and advertisements, manage your LocalBitcoins account by updating advertisements, automate trading and more.
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.
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.
If you are planning on integrating our API to your E-commerce platform, take a look at this guide.
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:
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:
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.
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.
The Apiauth-Signature is made by creating a string containing the following arguments and then hashing them with your HMAC authentication secret using SHA256.
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()
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.
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.
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.
A list of all API endpoints, both public and authenticated. Certain unauthenticated endpoints return more information if you send the request authenticated.
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| Required arguments | - | ||
|---|---|---|---|
| Optional arguments | - | ||
| Permissions | Read | ||
| HTTP method | GET |
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.
{
"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
}
}
| 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 |
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.
{
"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.
| Required arguments | - | ||
|---|---|---|---|
| Optional arguments | - | ||
| Permissions | Read | ||
| HTTP method | GET |
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.
| Argument | Type | Values | |
|---|---|---|---|
| Required arguments | ads | String | Comma separated list of advertisement IDs. |
| Optional arguments | - | ||
| Permissions | Read | ||
| HTTP method | GET |
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.
| 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 |
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.
| 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 |
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).
Creating Local advertisements functions the same as online advertisements but with a couple of differences:
| Required arguments | - | ||
|---|---|---|---|
| Optional arguments | - | ||
| Permissions | Read, Write | ||
| HTTP method | POST |
Sending a request to this endpoint with an advertisement ID created by the token owner deletes the advertisement.
| Argument | Type | Values | |
|---|---|---|---|
| Required arguments | contact_id | Integer | Trade ID number. |
| Optional arguments | - | ||
| Permissions | Money | ||
| HTTP method | POST |
Releases Bitcoin trades specified by ID {contact_id}. If the release was successful a message is returned on the data key.
| 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 |
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.
| Required arguments | - | ||
|---|---|---|---|
| Optional arguments | - | ||
| Permissions | Read, Write | ||
| HTTP method | POST |
Marks a trade as paid.
| Required arguments | - | ||
|---|---|---|---|
| Optional arguments | - | ||
| Permissions | Read | ||
| HTTP method | GET |
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.
| 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 |
Posts a message and/or uploads an image to the trade. Encode images with multipart/form-data encoding.
| Argument | Type | Values | |
|---|---|---|---|
| Required arguments | - | ||
| Optional arguments | topic | String | Short description of issue to LocalBitcoins customer support. |
| Permissions | Read, Write | ||
| HTTP method | POST |
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.
| Required arguments | - | ||
|---|---|---|---|
| Optional arguments | - | ||
| Permissions | Read, Write | ||
| HTTP method | POST |
Cancels the trade if the token owner is the Bitcoin buyer. Bitcoin sellers cannot cancel trades.
| Required arguments | - | ||
|---|---|---|---|
| Optional arguments | - | ||
| Permissions | Read, Write | ||
| HTTP method | POST |
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.
| 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 |
Creates or updates real name confirmation.
| Required arguments | - | ||
|---|---|---|---|
| Optional arguments | - | ||
| Permissions | Read, Write | ||
| HTTP method | POST |
Marks the identity of trade partner as verified. You must be the advertiser in this trade.
| 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 |
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).
| Required arguments | - | ||
|---|---|---|---|
| Optional arguments | - | ||
| Permissions | Read | ||
| HTTP method | GET |
Returns information about a single trade that the token owner is part in.
| Argument | Type | Values | |
|---|---|---|---|
| Required arguments | contacts | - | CSV list of trade ID numbers. |
| Optional arguments | - | ||
| Permissions | Read | ||
| HTTP method | GET |
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.
| Required arguments | - | ||
|---|---|---|---|
| Optional arguments | - | ||
| Permissions | - | ||
| HTTP method | GET |
List of valid and recognized countrycodes for LocalBitcoins.com. Return value is structured like so:
{
"data": {
"cc_list": ["fi", "fr", "us", ...],
"cc_count": 50
}
}
| Required arguments | - | ||
|---|---|---|---|
| Optional arguments | - | ||
| Permissions | - | ||
| HTTP method | GET |
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.
| Required arguments | - | ||
|---|---|---|---|
| Optional arguments | - | ||
| Permissions | Read | ||
| HTTP method | GET |
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"
}
}
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.
| 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. |
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.
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
All dashboard contact listings paginate. See the section on pagination.
| Required arguments | - | ||
|---|---|---|---|
| Optional arguments | - | ||
| Permissions | Read | ||
| HTTP method | GET |
Returns a list of all released trades where the token owner is either a buyer or seller. See /api/dashboard/ for more information.
| Required arguments | - | ||
|---|---|---|---|
| Optional arguments | - | ||
| Permissions | Read | ||
| HTTP method | GET |
Returns a list of all canceled trades where the token owner is either a buyer or seller. See /api/dashboard/ for more information.
| Required arguments | - | ||
|---|---|---|---|
| Optional arguments | - | ||
| Permissions | Read | ||
| HTTP method | GET |
Returns a list of all closed trades where the token owner is either a buyer or seller. See /api/dashboard/ for more information.
| 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 |
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.
| Required arguments | - | ||
|---|---|---|---|
| Optional arguments | - | ||
| Permissions | Read | ||
| HTTP method | POST |
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.
| Required arguments | - | ||
|---|---|---|---|
| Optional arguments | - | ||
| Permissions | Read | ||
| HTTP method | GET |
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/?..."
}
}
| 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 |
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.
| Required arguments | - | ||
|---|---|---|---|
| Optional arguments | - | ||
| Permissions | READ | ||
| HTTP method | GET |
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.
| Required arguments | - | ||
|---|---|---|---|
| Optional arguments | - | ||
| Permissions | Read, Write | ||
| HTTP method | POST |
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.
| Required arguments | - | ||
|---|---|---|---|
| Optional arguments | - | ||
| Permissions | Read | ||
| HTTP method | GET |
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
}
}
| Required arguments | - | ||
|---|---|---|---|
| Optional arguments | - | ||
| Permissions | Read | ||
| HTTP method | GET |
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"
}
]
}
| Required arguments | - | ||
|---|---|---|---|
| Optional arguments | - | ||
| Permissions | Read, Write | ||
| HTTP method | POST |
Marks a specific notification as read.
| Required arguments | - | ||
|---|---|---|---|
| Optional arguments | - | ||
| Permissions | - | ||
| HTTP method | GET |
Returns a list of valid payment methods. Also contains name and code for payment methods, and possible limitations in currencies and bank name choices.
| Required arguments | - | ||
|---|---|---|---|
| Optional arguments | - | ||
| Permissions | - | ||
| HTTP method | GET |
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.
| Argument | Type | Values | |
|---|---|---|---|
| Required arguments | pincode | Integer | 4 digit app PIN code set from profile settings |
| Optional arguments | - | ||
| Permissions | Read | ||
| HTTP method | POST |
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.
| 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 |
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.
| 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"}]
| Argument | Type | Values | |
|---|---|---|---|
| Required arguments | - | ||
| Optional arguments | after | Date | Return messages before date. UTC date in ISO 8601 format |
| Permissions | Read | ||
| HTTP method | GET |
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.
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 | — |
| Required arguments | - | ||
|---|---|---|---|
| Optional arguments | - | ||
| Permissions | Read | ||
| HTTP method | GET |
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/.
| Required arguments | - | ||
|---|---|---|---|
| Optional arguments | - | ||
| Permissions | Read | ||
| HTTP method | GET |
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.
| 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 |
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.
| 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 |
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.
| Required arguments | - | ||
|---|---|---|---|
| Optional arguments | - | ||
| Permissions | Read | ||
| HTTP method | POST |
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.
| Required arguments | - | ||
|---|---|---|---|
| Optional arguments | - | ||
| Permissions | - | ||
| HTTP method | - |
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.
| Required arguments | - | ||
|---|---|---|---|
| Optional arguments | - | ||
| Permissions | - | ||
| HTTP method | - |
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.
| Required arguments | - | ||
|---|---|---|---|
| Optional arguments | - | ||
| Permissions | - | ||
| HTTP method | - |
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/.
| Required arguments | - | ||
|---|---|---|---|
| Optional arguments | - | ||
| Permissions | - | ||
| HTTP method | - |
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/.
| Required arguments | - | ||
|---|---|---|---|
| Optional arguments | - | ||
| Permissions | - | ||
| HTTP method | - |
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/.
| Required arguments | - | ||
|---|---|---|---|
| Optional arguments | - | ||
| Permissions | - | ||
| HTTP method | - |
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/.
| Required arguments | - | ||
|---|---|---|---|
| Optional arguments | - | ||
| Permissions | - | ||
| HTTP method | - |
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/.
| Required arguments | - | ||
|---|---|---|---|
| Optional arguments | - | ||
| Permissions | - | ||
| HTTP method | - |
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/.
| Required arguments | - | ||
|---|---|---|---|
| Optional arguments | - | ||
| Permissions | - | ||
| HTTP method | - |
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/.
| Required arguments | - | ||
|---|---|---|---|
| Optional arguments | - | ||
| Permissions | - | ||
| HTTP method | - |
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/.
| Required arguments | - | ||
|---|---|---|---|
| Optional arguments | - | ||
| Permissions | - | ||
| HTTP method | - |
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/.
| Required arguments | - | ||
|---|---|---|---|
| Optional arguments | - | ||
| Permissions | - | ||
| HTTP method | - |
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/.
| Required arguments | - | ||
|---|---|---|---|
| Optional arguments | - | ||
| Permissions | - | ||
| HTTP method | - |
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/.
| Required arguments | - | ||
|---|---|---|---|
| Optional arguments | - | ||
| Permissions | - | ||
| HTTP method | - |
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/.
| Required arguments | - | ||
|---|---|---|---|
| Optional arguments | - | ||
| Permissions | - | ||
| HTTP method | - |
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/.
| Required arguments | - | ||
|---|---|---|---|
| Optional arguments | - | ||
| Permissions | - | ||
| HTTP method | - |
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/.
| Required arguments | - | ||
|---|---|---|---|
| Optional arguments | - | ||
| Permissions | - | ||
| HTTP method | - |
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.
| Required arguments | - | ||
|---|---|---|---|
| Optional arguments | - | ||
| Permissions | - | ||
| HTTP method | - |
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.
| Required arguments | - | ||
|---|---|---|---|
| Optional arguments | - | ||
| Permissions | - | ||
| HTTP method | - |
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
| 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 |