Introduction
BTCMap.org runs on the open-source treasure trove that is OpenStreetMap (OSM). If you want Bitcoiners to find places to blow sats anywhere on the planet, grab an OSM account and start mapping, no excuses.
Noobs 🙂
Only adding a handful of spots and don't plan to babysit them? Fill in the quick-add form and the community will queue it for you. Resources are tight, so if you've got an hour to spare, level-up and learn to edit OSM yourself.
Got questions? Hop into the BTC Map Matrix room and we'll sort you out.
Shadowy Supertaggers 🥷
Stack badges, earn sats, and recognition on BTC Map for your contributions. Your efforts will be featured on our leaderboard, and you will get your very own tagger profile too!
What you'll need
- A computer with two monitors (makes life easier)
- Access to OpenStreetMap (OSM), Gitea and Matrix
- Access to Facebook & Instagram for quick verifications
- Some OSM tagging experience, or the willingness to read our guide
- A careful eye and a bit of perseverance
Tip: use the same handle on OSM, Gitea and Matrix so we can ping you quickly if something looks odd
If you'd like, we'll pair you with a buddy who will walk you through tagging your very first ticket.
Keen to help? Please complete the Become a Tagger form.
Contributing
Add new locations or update existing ones directly as you see fit, or help with the backlog of submissions from the Noob Form at one of the links below:
If you're a serious tagger, please consider joining the Shadowy Supertagger Team and we'll provision you on our systems and guide you through our processes.
We also have a Supertagger Matrix room to get you on-boarded.
If you are specifically looking at adding Square merchants, then we have a dedicated guide here.
Please use the following guidance when contributing:
Physical Verification and Local Knowledge
Our main goal is to provide the public with an accurate dataset and locals know best. Please try to prioritize locations with close physical proximity to you. Make sure that you're relying on the most accurate data, such as:
- On-site survey
- Direct phone/email/socials
- Various online sources (be careful about copyright); not all online data is free to use! The official website of the merchant is usually the best online source.
Relying on a form submission without any additional checks is strongly discouraged. The information submitted should be verified to ensure we are adding accurate data to OpenStreetMap.
Double-check Coordinates
If taking on issues submitted from the Add Location form, you can and should make adjustments to the exact pin location if you notice it is incorrect. The person submitting the location will not be a mapping expert and that is ok - this is where the extra validation by the Supertagger can help improve the data accuracy. Any submissions with completely invalid locations (like in the middle of the ocean) can be closed as not-planned with the reason provided in a comment.
Source of Data
Each submission will contain information about the source of the data, so that taggers will know if it was completed by the business owner, a customer, or by another method. Some submissions may also include contact information, which can be used to follow up if further information is required.
Tagging Guidance
Tags in Use
The following tags drive the behavior of our apps, so please be as specific as you can when tagging.
The only required tag is currency:XBT.
currency:XBT
payment:lightning
payment:lightning_contactless
payment:onchain
check_date:currency:XBT
check_date
payment:lightning:operator=<operator>
Examples
currency:XBT=yes - This indicates that Bitcoin is accepted, but it does not specify which payment types are supported.
currency:XBT=no - This indicates that Bitcoin is not accepted.
payment:onchain=yes - This indicates that on-chain payments are accepted.
payment:onchain=no - This indicates that on-chain payments are not accepted.
payment:lightning=yes - This indicates that Lightning payments are accepted.
payment:lightning=no - This indicates that Lightning payments are not accepted.
payment:lightning_contactless=yes - This indicates that NFC Lightning payments are accepted.
payment:lightning_contactless=no - This indicates that NFC Lightning payments are not accepted.
payment:lightning:operator=square - To be applied for Square Imports.
check_date:currency:XBT=yyyy-mm-dd - This indicates the date when Bitcoin tags were checked/verified (for more information). Please use the correct ISO date format as shown.
check_date=yyyy-mm-dd - This indicates the date when all present tags were verified using local knowledge or extrapolation (for example, information obtained from the company's website). Please use the correct ISO date format as shown.
survey:date=yyyy-mm-dd - Use this tag when the location has been physically verified in person by you. Please use the correct ISO date format as shown.
You should verify all the present tags (if possible) when you are adding Bitcoin tags to an existing location.
Companion App Tags
In some cases, Bitcoin acceptance requires the use of 3rd party Companion Apps that generate invoices on behalf of the merchant. Sometimes the merchant is not even aware you are paying with bitcoin.
If a Companion App is required then the following tags should be used:
payment:lightning:requires_companion_app=yes
payment:lightning:companion_app_url=https://app-url-com
Addresses
The address tags should be filled out in accordance to local norms.
Certain integrations require locations to have specific address fields for locations to appear in their app. Known restrictions are:
- Cash App requires: name, address number, address street and address city/suburb
Legacy Tags
payment:bitcoin=yes - This is a very popular legacy tag implying both currency:XBT=yes and payment:onchain=yes. You should remove the payment:bitcoin=yes tag when adding the currency:XBT=yes tag.
We still search for these legacy tags for general display in the apps, but we won't be specific about the payment types supported. You should really remove them when updating with the current tagging rules.
Other OpenStreetMap tags
OpenStreetMap is an incredibly flexible platform with tags for a variety of different features.
Here are some useful links that may be useful for your location:
It is easy to look up all the available tags and their use cases in the OSM Wiki.
Changeset Comments
Every edit on OpenStreetMap has the option to add a changeset comment. This is an important way for other OSM contributors to get a quick idea of what the edit contained. You should include a short description of your changes in this field.
Please include:
- The
#btcmaphashtag in your changeset comments so that the activity is associated with our Organised Editing initiative. - Under
source, the Issue ID in the formissue:1234as a minimum. Refrain from using "Local Knowledge" as a proxy unless you have this first hand and be as specific as possible, e.g. "Confirmed via email with business owner".
Other OSM contributors may ask clarification questions, so please monitor your email and respond to any non-frivolous and respectful questions in a timely manner.
Nodes or Ways?
If an existing Node or Way exists, use whatever is already in place. If you are adding a new element, you should add a Node representing the merchant at that location. Local taggers will handle tagging buildings as Ways as appropriate.
More information on element types can be found here.
- Home
- Table of Contents
- Quicklinks: