{"number":21,"title":"URI Scheme","authors":["Nils Schneider","Matt Corallo"],"status":"Closed","type":"Specification","layer":"Applications","created":"2012-01-29","requires":[],"replaces":[20],"replacedBy":[321],"discussion":[],"abstract":"This BIP proposes a URI scheme for making Bitcoin payments.","eli5":"Defines the \"bitcoin:\" link format that packages an address, amount, label and message into one string, often shown as a QR code. Wallets read these links to fill in payment details automatically, reducing copy-and-paste mistakes.","categories":["payments","uri","usability"],"filename":"bip-0021.mediawiki","githubUrl":"https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki","format":"mediawiki","readingMinutes":4,"inbound":5,"revisions":39,"impact":92,"core":false,"references":[20,321],"lastModified":"2026-02-27","html":"

Superseded by BIP 321

\n

This BIP has been superseded and replaced with BIP 321. Please see BIP 321 instead.

\n

Original BIP

\n

This BIP is a modification of an earlier BIP 0020 by Luke Dashjr. BIP 0020 was based off an earlier document by Nils Schneider. The alternative payment amounts in BIP 0020 have been removed.

\n

Abstract

\n

This BIP proposes a URI scheme for making Bitcoin payments.

\n

Motivation

\n

The purpose of this URI scheme is to enable users to easily make payments by simply clicking links on webpages or scanning QR Codes.

\n

Specification

\n

General rules for handling (important!)

\n

Bitcoin clients MUST NOT act on URIs without getting the user's authorization. They SHOULD require the user to manually approve each payment individually, though in some cases they MAY allow the user to automatically make this decision.

\n

Operating system integration

\n

Graphical bitcoin clients SHOULD register themselves as the handler for the \"bitcoin:\" URI scheme by default, if no other handler is already registered. If there is already a registered handler, they MAY prompt the user to change it once when they first run the client.

\n

General Format

\n

Bitcoin URIs follow the general format for URIs as set forth in RFC 3986. The path component consists of a bitcoin address, and the query component provides additional payment options.

\n

Elements of the query component may contain characters outside the valid range. These must first be encoded according to UTF-8, and then each octet of the corresponding UTF-8 sequence must be percent-encoded as described in RFC 3986.

\n

ABNF grammar

\n

(See also a simpler representation of syntax)

\n
bitcoinurn     = \"bitcoin:\" bitcoinaddress [ \"?\" bitcoinparams ]\nbitcoinaddress = *base58\nbitcoinparams  = bitcoinparam [ \"&\" bitcoinparams ]\nbitcoinparam   = [ amountparam / labelparam / messageparam / otherparam / reqparam ]\namountparam    = \"amount=\" *digit [ \".\" *digit ]\nlabelparam     = \"label=\" *qchar\nmessageparam   = \"message=\" *qchar\notherparam     = qchar *qchar [ \"=\" *qchar ]\nreqparam       = \"req-\" qchar *qchar [ \"=\" *qchar ]
\n

Here, \"qchar\" corresponds to valid characters of an RFC 3986 URI query component, excluding the \"=\" and \"&\" characters, which this BIP takes as separators.

\n

The scheme component (\"bitcoin:\") is case-insensitive, and implementations must accept any combination of uppercase and lowercase letters. The rest of the URI is case-sensitive, including the query parameter keys.

\n

Query Keys

\n\n\n\n\n

Transfer amount

\n

If an amount is provided, it MUST be specified in decimal BTC. All amounts MUST contain no commas and use a period (.) as the separating character to separate whole numbers and decimal fractions. I.e. amount=50.00 or amount=50 is treated as 50 BTC, and amount=50,000.00 is invalid.

\n

Bitcoin clients MAY display the amount in any format that is not intended to deceive the user. They SHOULD choose a format that is foremost least confusing, and only after that most reasonable given the amount requested. For example, so long as the majority of users work in BTC units, values should always be displayed in BTC by default, even if mBTC or TBC would otherwise be a more logical interpretation of the amount.

\n

Rationale

\n

Payment identifiers, not person identifiers

\n

Current best practices are that a unique address should be used for every transaction. Therefore, a URI scheme should not represent an exchange of personal information, but a one-time payment.

\n

Accessibility (URI scheme name)

\n

Should someone from the outside happen to see such a URI, the URI scheme name already gives a description. A quick search should then do the rest to help them find the resources needed to make their payment. Other proposed names sound much more cryptic; the chance that someone googles that out of curiosity are much slimmer. Also, very likely, what he will find are mostly technical specifications - not the best introduction to bitcoin.

\n

Forward compatibility

\n

Variables which are prefixed with a req- are considered required. If a client does not implement any variables which are prefixed with req-, it MUST consider the entire URI invalid. Any other variables which are not implemented, but which are not prefixed with a req-, can be safely ignored.

\n

Backward compatibility

\n

As this BIP is written, several clients already implement a bitcoin: URI scheme similar to this one, however usually without the additional \"req-\" prefix requirement. Thus, it is recommended that additional variables prefixed with req- not be used in a mission-critical way until a grace period of 6 months from the finalization of this BIP has passed in order to allow client developers to release new versions, and users of old clients to upgrade.

\n

Appendix

\n

Simpler syntax

\n

This section is non-normative and does not cover all possible syntax. Please see the BNF grammar above for the normative syntax.

\n

[foo] means optional, <bar> are placeholders

\n
<nowiki>bitcoin:<address>[?amount=<amount>][?label=<label>][?message=<message>]</nowiki>
\n

Examples

\n

Note: The addresses used in these examples are intentionally invalid to prevent accidental transactions.

\n

Just the address:

\n
bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W
\n

Address with name:

\n
bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?label=Luke-Jr
\n

Request 20.30 BTC to \"Luke-Jr\":

\n
bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=20.3&label=Luke-Jr
\n

Request 50 BTC with message:

\n
bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=50&label=Luke-Jr&message=Donation%20for%20project%20xyz
\n

Some future version that has variables which are (currently) not understood and required and thus invalid:

\n
bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?req-somethingyoudontunderstand=50&req-somethingelseyoudontget=999
\n

Some future version that has variables which are (currently) not understood but not required and thus valid:

\n
bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?somethingyoudontunderstand=50&somethingelseyoudontget=999
\n

Characters must be URI encoded properly.

\n

Reference Implementation

\n

Bitcoin-Qt supports the old version of Bitcoin URIs (ie without the req- prefix), with Windows and KDE integration as of commit 70f55355e29c8e45b607e782c5d76609d23cc858.

","toc":[{"id":"superseded-by-bip-321","title":"Superseded by BIP 321","level":2},{"id":"original-bip","title":"Original BIP","level":2},{"id":"abstract","title":"Abstract","level":2},{"id":"motivation","title":"Motivation","level":2},{"id":"specification","title":"Specification","level":2},{"id":"general-rules-for-handling-important","title":"General rules for handling (important!)","level":3},{"id":"operating-system-integration","title":"Operating system integration","level":3},{"id":"general-format","title":"General Format","level":3},{"id":"abnf-grammar","title":"ABNF grammar","level":3},{"id":"query-keys","title":"Query Keys","level":3},{"id":"transfer-amount","title":"Transfer amount","level":4},{"id":"rationale","title":"Rationale","level":2},{"id":"payment-identifiers-not-person-identifiers","title":"Payment identifiers, not person identifiers","level":3},{"id":"accessibility-uri-scheme-name","title":"Accessibility (URI scheme name)","level":3},{"id":"forward-compatibility","title":"Forward compatibility","level":2},{"id":"backward-compatibility","title":"Backward compatibility","level":2},{"id":"appendix","title":"Appendix","level":2},{"id":"simpler-syntax","title":"Simpler syntax","level":3},{"id":"examples","title":"Examples","level":3},{"id":"reference-implementation","title":"Reference Implementation","level":2}],"history":{"totalCommits":39,"firstCommit":"2012-01-30T00:01:49+00:00","lastUpdated":"2026-02-27T14:12:41-08:00","events":[{"sha":"b3a069464a8879dd858c392a788c9d19a9f7a075","date":"2026-02-27T14:12:41-08:00","author":"Murch","message":"Fix other broken anchors","url":"https://github.com/bitcoin/bips/commit/b3a069464a8879dd858c392a788c9d19a9f7a075","kind":"edit"},{"sha":"95465e0b4f7e18f401c20a203dcd02e056cb6878","date":"2026-02-27T15:43:46-08:00","author":"Jon Atack","message":"BIP20,21: add Superseded-By and Replaces headers (#1984)","url":"https://github.com/bitcoin/bips/commit/95465e0b4f7e18f401c20a203dcd02e056cb6878","kind":"edit"},{"sha":"24e96e870fffaa257b465ce1f0370c14aac588e8","date":"2025-10-08T14:59:36-07:00","author":"Murch","message":"process: Created ↦ Assigned","url":"https://github.com/bitcoin/bips/commit/24e96e870fffaa257b465ce1f0370c14aac588e8","kind":"edit"},{"sha":"5207ef92a52d0b8902895b0dbb40823a4d698ec9","date":"2025-04-11T20:08:17-07:00","author":"Murch","message":"process: Author ↦ Authors","url":"https://github.com/bitcoin/bips/commit/5207ef92a52d0b8902895b0dbb40823a4d698ec9","kind":"edit"},{"sha":"59730dec4fb641a41589aa1b91d3c452f13e0e36","date":"2025-04-11T20:05:13-07:00","author":"Murch","message":"process: Remove Comments-URI and -Summary","url":"https://github.com/bitcoin/bips/commit/59730dec4fb641a41589aa1b91d3c452f13e0e36","kind":"edit"},{"sha":"a233bde4af52c6a11269e2e6dd9707abce441ffe","date":"2025-04-11T18:19:21-07:00","author":"Murch","message":"process: Standards Track ↦ Specification","url":"https://github.com/bitcoin/bips/commit/a233bde4af52c6a11269e2e6dd9707abce441ffe","kind":"edit"},{"sha":"ff1f3b36f8a535930ddaa76733fe628739372f70","date":"2025-04-11T18:17:21-07:00","author":"Murch","message":"process: Superseded-By ↦ Proposed-Replacement","url":"https://github.com/bitcoin/bips/commit/ff1f3b36f8a535930ddaa76733fe628739372f70","kind":"status"},{"sha":"66defbdc03ad64ccddfd373e1c59af9a41ab990f","date":"2025-04-11T18:11:55-07:00","author":"Murch","message":"process: Deferred/Obsolete/Rejected/Replaced/Withdrawn ↦ Closed","url":"https://github.com/bitcoin/bips/commit/66defbdc03ad64ccddfd373e1c59af9a41ab990f","kind":"status"},{"sha":"c7e9befc2efaef2eccec3831c97780573d99988e","date":"2025-08-06T12:59:50+00:00","author":"Matt Corallo","message":"Mark BIP 21 as replaced (by BIP 321) and mark BIP 321 as Proposed","url":"https://github.com/bitcoin/bips/commit/c7e9befc2efaef2eccec3831c97780573d99988e","kind":"status"},{"sha":"fad325e7a11902ca7e73fece9ee78985e9dcd844","date":"2025-06-04T15:57:44-04:00","author":"ethicnology","message":"refactor: add warning about invalid example addresses in BIP-21","url":"https://github.com/bitcoin/bips/commit/fad325e7a11902ca7e73fece9ee78985e9dcd844","kind":"edit"},{"sha":"448de3cafd1c52f2e4b72c608f518e7cd261ca9c","date":"2024-04-25T10:23:28-04:00","author":"Ava Chow","message":"21: Remove other libraries from reference implementations","url":"https://github.com/bitcoin/bips/commit/448de3cafd1c52f2e4b72c608f518e7cd261ca9c","kind":"edit"},{"sha":"3e10085c09f1322691cb6a22355f30ae54c1eab5","date":"2022-12-18T21:49:26-06:00","author":"D++","message":"Update Anchor Link","url":"https://github.com/bitcoin/bips/commit/3e10085c09f1322691cb6a22355f30ae54c1eab5","kind":"edit"},{"sha":"dd39e2234c23e6efbc77802caa7e74093ae6a66e","date":"2021-04-26T22:55:25+02:00","author":"Dr. Maxim Orlovsky","message":"BIP-21 remove of all \"size\" mentions","url":"https://github.com/bitcoin/bips/commit/dd39e2234c23e6efbc77802caa7e74093ae6a66e","kind":"edit"},{"sha":"a29c14f66464b411db44a5a369a2cad5d8e5b44a","date":"2021-03-06T02:13:08+01:00","author":"Dr. Maxim Orlovsky","message":"Removing size param (not used anymore)","url":"https://github.com/bitcoin/bips/commit/a29c14f66464b411db44a5a369a2cad5d8e5b44a","kind":"edit"},{"sha":"959fecc15bdad070afa63455468b1dba54655fa6","date":"2016-11-30T09:47:31+00:00","author":"Luke Dashjr","message":"Promote BIP 2 Draft->Active, and implement it","url":"https://github.com/bitcoin/bips/commit/959fecc15bdad070afa63455468b1dba54655fa6","kind":"status"},{"sha":"72f18918a8ae655212ea2700b30f0dc4d758b843","date":"2016-11-30T09:45:33+00:00","author":"Luke Dashjr","message":"Promote BIP 123 Draft->Active, and implement it","url":"https://github.com/bitcoin/bips/commit/72f18918a8ae655212ea2700b30f0dc4d758b843","kind":"status"},{"sha":"6fb5aaf1366099c7107de58b55159986cdc2549e","date":"2016-07-22T14:52:15-03:00","author":"Elias Rodrigues","message":"Minor link fix","url":"https://github.com/bitcoin/bips/commit/6fb5aaf1366099c7107de58b55159986cdc2549e","kind":"edit"},{"sha":"e00a157306878c732a93bb2f2ea456701886858d","date":"2016-07-18T00:37:10+01:00","author":"Sandro Machado","message":"Add Swift Library","url":"https://github.com/bitcoin/bips/commit/e00a157306878c732a93bb2f2ea456701886858d","kind":"edit"},{"sha":"c65874246a3ac5f55a9b10acc1aa22177c8d2050","date":"2016-01-29T11:14:59+11:00","author":"Daniel Cousens","message":"Add BIP21 Javascript library","url":"https://github.com/bitcoin/bips/commit/c65874246a3ac5f55a9b10acc1aa22177c8d2050","kind":"edit"},{"sha":"7509fae0be1f0f0effa1d6a1109a4a03afed8850","date":"2016-02-16T22:18:45+00:00","author":"Sandro Machado","message":"Update bip-0021.mediawiki","url":"https://github.com/bitcoin/bips/commit/7509fae0be1f0f0effa1d6a1109a4a03afed8850","kind":"edit"},{"sha":"e22ad0cd715af88cabecffe1afcc4258740dc85f","date":"2016-02-01T20:36:37+00:00","author":"Luke Dashjr","message":"Revert \"Update BIP-21 URI scheme for payment code support\"","url":"https://github.com/bitcoin/bips/commit/e22ad0cd715af88cabecffe1afcc4258740dc85f","kind":"edit"},{"sha":"f31f7d43473fadcfafbc886b15e8c488654839c2","date":"2016-02-01T20:14:22+00:00","author":"Luke Dashjr","message":"Promote Accepted->Final BIPs 11, 14, 21, 22, 23, 31, 32, 34, 35, 37, 65","url":"https://github.com/bitcoin/bips/commit/f31f7d43473fadcfafbc886b15e8c488654839c2","kind":"status"},{"sha":"2e6e5cf9589778ea55c7e71aa27e2b9ff122b737","date":"2015-06-25T11:30:18-05:00","author":"Justus Ranvier","message":"Update BIP-21 URI scheme for payment code support","url":"https://github.com/bitcoin/bips/commit/2e6e5cf9589778ea55c7e71aa27e2b9ff122b737","kind":"edit"},{"sha":"1647c7e6d3e3866454b803fd874df2d0c4991f4a","date":"2014-04-05T13:46:56+02:00","author":"Wladimir J. van der Laan","message":"Change date format to ISO 8601","url":"https://github.com/bitcoin/bips/commit/1647c7e6d3e3866454b803fd874df2d0c4991f4a","kind":"edit"},{"sha":"116129c6878a14415afba89e90b8ddd3a12b477e","date":"2014-03-10T18:10:27-07:00","author":"William Swanson","message":"BIP 21: Allow empty addresses and query parameters","url":"https://github.com/bitcoin/bips/commit/116129c6878a14415afba89e90b8ddd3a12b477e","kind":"edit"},{"sha":"6f15f98b1256bfe097962b0e9ad56ed9c5e5ab7c","date":"2014-03-10T18:04:10-07:00","author":"William Swanson","message":"BIP 21: Clarify case-sensitivity","url":"https://github.com/bitcoin/bips/commit/6f15f98b1256bfe097962b0e9ad56ed9c5e5ab7c","kind":"edit"},{"sha":"c823eeb5964be9abec8b146293ee82933be7ca72","date":"2014-03-06T17:57:42-08:00","author":"William Swanson","message":"BIP 21: Precisely define the valid query characters","url":"https://github.com/bitcoin/bips/commit/c823eeb5964be9abec8b146293ee82933be7ca72","kind":"edit"},{"sha":"0ee7ff7beddeb9e4beb04a4fd9fd4071687963f1","date":"2014-03-06T17:34:26-08:00","author":"William Swanson","message":"BIP 21: Mention RFC 3986 and character set","url":"https://github.com/bitcoin/bips/commit/0ee7ff7beddeb9e4beb04a4fd9fd4071687963f1","kind":"edit"},{"sha":"9f3dc5d7a556664cd7640b8cac4687cfb17f474b","date":"2014-03-06T17:15:33-08:00","author":"William Swanson","message":"BIP 21: Add a missing \"&\" rule to the ABNF grammar","url":"https://github.com/bitcoin/bips/commit/9f3dc5d7a556664cd7640b8cac4687cfb17f474b","kind":"edit"},{"sha":"d9e890a8f27e46806238e298a346397871fd7e87","date":"2013-10-21T02:18:47-04:00","author":"Peter Todd","message":"Fix formatting","url":"https://github.com/bitcoin/bips/commit/d9e890a8f27e46806238e298a346397871fd7e87","kind":"edit"},{"sha":"86e1074d7fd4b4d67a373e662b68df2998a28cc5","date":"2013-10-21T00:48:04-04:00","author":"Peter Todd","message":"Archive Revision as of 18:45, 23 May 2013","url":"https://github.com/bitcoin/bips/commit/86e1074d7fd4b4d67a373e662b68df2998a28cc5","kind":"edit"},{"sha":"1f64d2b06d628dffdc297be9a8afbb9da4e6b6ca","date":"2013-10-21T00:32:10-04:00","author":"Peter Todd","message":"Rename to mediawiki extension","url":"https://github.com/bitcoin/bips/commit/1f64d2b06d628dffdc297be9a8afbb9da4e6b6ca","kind":"rename"},{"sha":"f8c3c7554d0883c75fd973881da57161d6f90394","date":"2012-02-07T15:45:06-05:00","author":"Matt Corallo","message":"Clarify the req- prefix a bit.","url":"https://github.com/bitcoin/bips/commit/f8c3c7554d0883c75fd973881da57161d6f90394","kind":"edit"},{"sha":"6e2d2667f3a3248577b92578168de82c917ca8a2","date":"2012-02-05T12:15:42+00:00","author":"genjix","message":"Accepted BIP 21 for URI Scheme","url":"https://github.com/bitcoin/bips/commit/6e2d2667f3a3248577b92578168de82c917ca8a2","kind":"edit"},{"sha":"f068f6099ac11a63c9ebb60924bf0bc597144cf3","date":"2012-02-04T12:11:33-05:00","author":"Matt Corallo","message":"Describe message parameter better.","url":"https://github.com/bitcoin/bips/commit/f068f6099ac11a63c9ebb60924bf0bc597144cf3","kind":"edit"},{"sha":"e4622a82872fe7464ff816776fb7a615bbd895c1","date":"2012-01-31T17:49:11-05:00","author":"Matt Corallo","message":"replace req: with req-.","url":"https://github.com/bitcoin/bips/commit/e4622a82872fe7464ff816776fb7a615bbd895c1","kind":"edit"},{"sha":"1a40c520f88cb8dca0ba36e14ce3c9dc02c83b5b","date":"2012-01-31T16:23:44-05:00","author":"Matt Corallo","message":"Various update to bip 21.","url":"https://github.com/bitcoin/bips/commit/1a40c520f88cb8dca0ba36e14ce3c9dc02c83b5b","kind":"edit"},{"sha":"c39fc5053359cf62030caab05f8519fba8a611c5","date":"2012-01-30T00:17:02+00:00","author":"genjix","message":"tcatm supports BIP 0021 not BIP 0020. claims he did not support BIP 0020 which only came into existence a few months ago. Also according to BIP 0001, BIP champions are allowed to relinquish themselves from BIP.","url":"https://github.com/bitcoin/bips/commit/c39fc5053359cf62030caab05f8519fba8a611c5","kind":"edit"},{"sha":"6a5b4f3b080815c1ddff881e7a8491f5acca4fab","date":"2012-01-30T00:01:49+00:00","author":"genjix","message":"URI scheme sans x notation","url":"https://github.com/bitcoin/bips/commit/6a5b4f3b080815c1ddff881e7a8491f5acca4fab","kind":"edit"}]}}