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 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 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 which can be used when you want to create applications for other users (e.g.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 .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 Most API requests need to be encoded with 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 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 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 .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.bitcoin isinA good trick to creating the nonce is to use the unix timestamp in milliseconds.ethereum demoThis 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.bitcoin miner für androidMost API requests need to be encoded as , when uploading files multipart/form-data encoding is also supported.ethereal download for windows 7 64 bit

With most programming languages you can urlencode your API requests using standard functions.With Python you can use .Example: which results in .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: Return values are UTF-8 encoded JSON with the following metadata structure, which corresponds to an API request with the return value: If the API request ended in an unrecoverable error, there is no top level field.games like bitcoin billionaireThis helps against accidentally using an error message as legitimate data, creating confusing situations.bitcoin reitErrors 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 field that contains an object with the fields and .The error object can contain more fields if specified on the error documentation.The field is meant to be read by the application, the field is meant to be human readable.An example error return object: You can find a full list of error codes and .If there are too many values to return at once the results will be paginated.Pagination lives in the field of the returned JSON object.If there are no pages, the field is undefined.If there are more than one page, the field defines the field.If you've requested the last page, only the field is defined.On intermediate pages the object contains both the and fields.The and fields are URLs pointing to the respective page.They are usable as is.Example of a paginated return value: 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 fields returned can be specified.

Use a request parameter of , which is a comma-separated list of field names.Only those fields will be returned in the data.If the parameter is not given, all fields are returned.If an empty 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 structure., 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./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 /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: If the token owner can create a trade with the advertisement, the contact form URL is also returned.

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/countrycodes/ Required arguments - Optional arguments - Permissions - HTTP method GET Description .Return value is structured like so: /api/currencies/ Required arguments - Optional arguments - Permissions - HTTP method GET Description .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.All contacts where the token owner is participating are returned.Structure of common values to all contacts is follows: 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.SEPA Online buy Buyer and seller data.account_details 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./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.

/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}/./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: 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}./api/notifications/ Required arguments - Optional arguments - Permissions Read HTTP method GET Description Returns recent notifications.Example result can be seen below: /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./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./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.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: 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.

pincode Integer Token owners PIN code.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./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 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.countrycode is exactly two characters./buy-bitcoins-online/{currency:3}/{payment_method}/.json Required arguments - Optional arguments - Permissions - HTTP method - Description This API returns buy Bitcoin online ads./buy-bitcoins-online/{currency:3}/.json Required arguments - Optional arguments - Permissions - HTTP method - Description This API returns buy Bitcoin online ads./buy-bitcoins-online/{payment_method}/.json Required arguments - Optional arguments - Permissions - HTTP method - Description This API look up buy Bitcoin online ads./buy-bitcoins-online/.json Required arguments - Optional arguments - Permissions - HTTP method - Description This API returns buy Bitcoin online 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./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./sell-bitcoins-online/{countrycode:2}/{country_name}/.json Required arguments - Optional arguments - Permissions - HTTP method - Description This API returns sell Bitcoin online ads./sell-bitcoins-online/{currency:3}/{payment_method}/.json Required arguments - Optional arguments - Permissions - HTTP method - Description This API returns sell Bitcoin online ads./sell-bitcoins-online/{currency:3}/.json Required arguments - Optional arguments - Permissions - HTTP method - Description This API returns sell Bitcoin online ads.

/sell-bitcoins-online/{payment_method}/.json Required arguments - Optional arguments - Permissions - HTTP method - Description This API returns sell Bitcoin online ads./sell-bitcoins-online/.json Required arguments - Optional arguments - Permissions - HTTP method - Description This API returns sell Bitcoin online 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.