Bitcoin Tagging

I think there is a need to rationalise and disambiguate the tagging for Bitcoin.

There is now consensus that places that accept the Bitcoin ‘currency’ as payment should use the currency:XBT tag, which seems sensible. Historically, people have used (and still do use) ‘payment=bitcoin’ to denote the same thing.

There are now new payment methods for Bitcoin the ‘currency’; namely Bitcoin Lightning and Bitcoin Lightning NFC. These are in addition to the original on-chain ‘payment method’ that is implicitly implied in the ‘payment:bitcoin’ tag.

The following seems most logical to me:

  • currency:XBT and bitcoin=accepted (deprecated) - Bitcoin the currency accepted.
  • payment:lightning - Lightning accepted. as a payment method.
  • payment:lightningnfc - Lightning NFC accepted as a payment method.
  • payment:onchain - Onchain accepted as a payment method.


  • The payment tags listed could be used in combination with other currencies.
  • There are screnarios where Bitcoin will only be accepted via the Lightning ‘payment method’.
  • There is a also discussion to be had around the migration of payment:bitcoin to currency:XBT AND payment:onchain. Historicially, payment:bitcoin implied onchain acceptance of Bitcoin as Lightning as a payment method didn’t exist.

What are peoples thoughts?

Reference links:

1 Like

Further reference links:

I think that bitcoin payments are such a niche and there’s so much churn
in the bitcoin payment sector (people starting to accept it because it’s
the hip thew thing, then stopping again because the income doesn’t
justify the cost; new wireless methods being invented and marketed but
dying out after a short while etc.) that I would advise against (a)
mapping it, or at least (b) trying to formalize the mapping of it.

Whenever I encountered anything bitcoin related in OSM it was either a
shabby import of ATMs or some fanboi copying data from some bitcoin
directory. It has never been a serious endeavour, always been a niche
thing executed by people who didn’t care about OSM at all except for
plastering it with bitcoin tags.

I’d therefore just leave things alone and not encourage them further.


I agree with your sentiment, which is why I’d like to do it properly with merchant support. There are lots of grass roots activities going on right now using things like Google Maps. I think we can do better!

1 Like

We already have a tag for Bitcoin point of sale / Point of Interest.

Are you trying to suggest that people can not pay at a Bitcoin BTC point of sale unless it is a certain kind? The already quite small number of places people can pay would in that case just be further divided and its losing its point.

And if this isn’t the case, if people don’t really care if its onchain or lightning or NFC, then why tag it?

Hi Tom,

Which tag are you referring to?

Are you trying to suggest that people can not pay at a Bitcoin BTC point of sale unless it is a certain kind?

I’m stating that merchants can receive the Bitcoin currency (XBT) via a number of different payment methods. A customer may not have the payment method that the vendor supports.

It’s entirely analogous to having currency:EUR=yes and say payment:cash=no. I could not use a €20 note at that vendor.

The already quite small number of places people can pay would in that case just be further divided and its losing its point.

I’m not suggesting splitting. The currency:XBT tag covers the general case and the payment tags add further detail on the how.

if people don’t really care if its onchain or lightning or NFC, then why tag it?

People do care, certainly Bitcoiners. There are many country specific Google Map style implementations popping up to support local needs.


Mapping payment methods for everything but vending machines and 24/7 gas stations was a mistake in the first place, no reason to complicate it any further.

Bitcoin is both a currency and a loose set of payment protocols. The most basic kind of payment is “on-chain”, and it takes ~10 minutes. There are plenty of places where it’s not practical to accept such payments.

Lightning Network is a protocol which allows people to transfer bitcoins instantaneously, so it’s more like an optional POS firmware update in a sense that it’s going to replace most on-chain payments eventually. Faster payments are important for merchants and their customers alike. As a user of an OSM-based Bitcoin merchant map, I always prefer lightning-enabled places when I have a choice, and that’s a common need in this niche.

Although the number of Bitcoin merchants is small, OSM is the only truly open database people can rely on, and this data set is being maintained and updated on a daily basis. OSM now has about ~7,000 such elements, which is rather small but certainly non-negligible.

That said, tagging Bitcoin is really hard. How would you feel about something like this:

payment:bitcoin = yes (legacy, no way to infer whether LN is supported)
payment:bitcoin = “onchain” (only onchain payments are accepted)
payment:bitcoin = “lightning” (only LN payments are accepted)

The value string can be up to 255 chars so there is no problem with listing a few values separated by commas. Having a single tag for all Bitcoin-related metadata looks like a cleaner approach, and no one is really using XBT ticker so it looks odd anyway. The BTC ticker conflicts with the ISO rules, so both of those options are subpar.

1 Like

I really like this tagging approach for payment method.

I feel we should also use the currency:XBT as that is aligned with the treatment of other currencies.

This approach gives us a single bitcoin:payment tag that we can then add detail to. It also allows this tag (the most popular) to evolve and continue to be used, albeit for a slightly different purpose.

The reply from Igor makes something clear;

(map) users can’t expect to be able to pay JUST because a merchant is tagged as accepting BTC.

As an aside, this used to be “payment:xbt”, today this is “currency:xbt”, same thing just that the former is deprecated due to crypto currencies being currencies.

So, when a user that only has “on-chain” payment possibility finds a merchant that doesn’t accept it, or vice versa with lightning, then you have to admit that the group of possible places you can pay just split into two.

Like Fredrik I have doubts that the information we currently have in OSM is actually still valid, from what I’ve seen most places don’t keep accepting it very long. With this split where fans of BTC basically need to be able to pay using two different wallets, that is likely just make things worse.

On the other hand I understand the position that you don’t want to create a new map. Though competing crypto currencies do that and it works for them.

But, yeah, it very much feels like the BTC community doesn’t take the work of maintaining the data very seriously. And that makes it the problem of OSM, which is why we should have this discussion of approach.

I personally have not seen much effort into maintaining (that means checking accuracy regularly) this data in OSM and I really like to point Nathan in that direction.

The difference you want to tag sounds like a hell to maintain, violates the basic “map whats on the ground” principle since there is no way to find out which payment method is supported without actually buying something. (please don’t tell me the merchant will know the difference between on-chain and lightning).

In short, I don’t think this belongs in OSM.

This is absolutely what I’m trying to change. I will be connecting with grassroots Bitcoin communities across to globe so we can get local ownership.

There are many local Bitcoin meetups all over the world now and they are increasing all the time. Many are technically focussed and have the skills and mindsets to contribute.

1 Like

Personally, my biggest issue with this data set is consistency.

Comparing those two numbers, it’s obvious that people prefer payment:bitcoin, but this tagging method is against the rules. Are there any tools to force new contributors to follow a specific pattern? I doubt that everyone reads the Wiki and payment:bitcoin is just a more intuitive choice.


I don’t know… Nobody will deny that Bitcoin is a “Cryptocurrency”, right?

It is indeed needed to make this more clear to BTC mappers.

@nathan_day is it possible to first focus on data-consistency and data being up-to-date?

Changing from the ‘payment’ tag to the ‘currency’ tag and when a location is verified in-person, adding a Key:survey:date - OpenStreetMap Wiki tag would be a great way to start.
And that includes deleting the tags if the merchant no longer does accept it.

I’d personally be quite reluctant adding new tags until we can see that the current data can be maintained by that same community.

Please refer them to the Cryptocurrency - OpenStreetMap Wiki page instead of the Bitcoin one, we don’t want every crypto community to re-invent the wheel.

True, but nobody will deny that it’s unusable without a payment network, so the question is which of those traits is more important in this specific context.

Another issue with currency:XBT is the fact that XBT is a made-up and completely unrelated ticker symbol. You called us “BTC mappers” for a reason =) Bitcoin is BTC, and there is a lot of hard data to back up that claim. Store owners are using it in their ads, all the popular exchanges and brokers recognize BTC ticker and even the mainstream financial portals like Yahoo Finance call it BTC. Same goes to most of financial data feeds and APIs. We can’t keep calling it an incorrect name and expect people to follow the guidelines which are out-of-touch with reality, it’s like expecting people to walk on their hands.

Updating 7,500 places to follow an unpopular (~500 places) and clearly flawed pattern seems a bit counterproductive. It’s a good example of revealed preferences, most merchants see Bitcoin as a yet another payment method, so this tag just indicates that they have a POS terminal connected to this specific payment network.

My point is that we should analyze the root causes of the current mess, doubling down on an unpopular approach can only make things worse.


why isn‘t going there and buying something not following the on the ground principle? You may have some valid critique, but this one isn’t, accepted payment methods can easily be checked on the ground (and buying is not necessary, asking should be sufficient)


Please refer to the explanation on Cryptocurrency - OpenStreetMap Wiki

Early Bitcoin BTC mappers picked it a very long time ago based on “XBT” being an part of an ISO standard. So its not made up by openstreetmap. But I honestly have no more knowledge on that history than that.

You misunderstood. Most of those tags are not recent. Some are 5 or more years old. What is the chance that those stores are still accepting BTC?
History shows us that a lot of places try this for a while, then stop when they realize its not as popular anymore. Turns out, nobody removes them from OSM when that happens.

To avoid this becoming a “number go up” game, the old tagged stores should be verified to still be accepting it. Otherwise it is not valuable for openstreetmap. And that is our main goal, which I hope we share.

And, yeah, when those people go and verify those local places and add a tag stating it is verified, it should be pretty easy to alter the payment tag to a currency tag in the same dialog, would you not agree?

The basis here is from Verifiability - OpenStreetMap Wiki

The core sentence here is; A tag/value combination and geometry is verifiable if and only if independent users observing the same feature would make the same observation every time.

And the problem with ‘on-chain’ vs ‘lightning’ is that the person doing the mapping needs quite a bit of technical knowledge to understand the difference and indeed the store clerk will not know the difference.
So, your generic openstreetmap mapper can in actual fact not verify this independently. They can verify (typically through a sticker or asking a clerk) if the store accepts some crypto, but technical details like explaining the different between LN and on-chain are quite a bit more difficult.


to me this seems sufficient for satisfying ground verifiability.


I’m well aware of that, did you see something which contradicts my points?

I can’t say I know more about this historical twist, but it seems that those mappers are in minority, probably they just tried to follow the rules, so we can’t even claim that those guys agreed with this XBT thing.

I follow every update and I can assure you, currency:XBT is still widely unpopular. Here is a few examples with timestamps:

If the rules don’t make sense, the majority of people will ignore them. Still, there will always be a camp who would blindly follow the rules no matter how absurd they are, and the end result is more chaos. And there is also a third camp, those who mix all of those tags “just in case”. In my opinion, the only way to boost consistency is to hear the majority, understand their reasoning and introduce a sensible set of rules.

Is there a reason to wait on that? Inaction won’t stop the flow of new places from the mappers who have no idea what is XBT. They will keep ignoring it, adding to accumulated inconsistencies. It’s clear that this rule is the source of confusion, why waste energy going against the flow? That’s basically what I’m trying to say, there is no way of stopping common sense, people will have it their way, because they don’t really care about our opinions and the system allows them to ignore the rules. Thus, the best course of action is either to introduce agreeable rules, or to shove the current rules down the throats of the mappers, if it’s even technically possible. Verifying places improves quality, tagging rules boost consistency, we can totally have both at the same time.

1 Like

I literally have no preference on the BTC vs XBT topic. Igor brought this up while we were discussing introducing new payment tags.

My important point is that the payment:lightning and/or the payment:lightningnfc and/or payment:onchain tag(s) being introduced is not helpful as that splinters the correctness of the current dataset even more than it already is.

If BTC mappers want to improve the OpenStreetmap dataset, I suggest they start with verifying the current dataset using survey:date and removing the suspected big percentage of tags that are no longer accurate.

While they are in there those mappers could also change the payment tag which was historically used to switch them to the currency tag which was decided (years ago) in OSM to be the more fitting tag for crypto currencies.

For further changes, please remember that while OSM is an open database, we still do things by consensus because while its easy to change things, there are a lot of consumers of this data that need to likewise follow any changes. So changes need time and things need coordination and communication.

These values I explain here are things you’ll find repeated by any other long-time OSM editor. Please do verify this by joining the IRC channel (or its Matrix counterpart), so you know its not just nasty old me :wink:

Be nice, leave things cleaner and better then when you arrived.

I agree. We are proposing adding to the single payment:bitcoin tag to detail the supported payment types where appropriate. This will refine and clense the existing dataset, which is by far the largest.

I have people from all over the world ready to start verifying, cleansing and enhancing this dataset.