Stacks Pay: A Payment Request Standard for Stacks Blockchain Payments by dantrevino · Pull Request #202 · stacksgov/sips

dantrevino · 2024-12-02T07:25:02Z

Stacks Pay is a proposed standard for wrapping transaction information in a standard way for easy sharing.

binxbrigandine · 2024-12-02T22:08:44Z

Love standardization!

markmhendrickson · 2024-12-04T11:18:34Z

Thanks for proposing, @dantrevino! We'll review on the Leather team and provide thoughts.

kyranjamie

Great work @dantrevino

sips/sip-02x/sip-02x-stacks-pay.md

whoabuddy

Overall looks good, happy to see you're putting this forward! I left a few small comments.

@human058382928 @r0zar @biwasbhandari these encoded URLs describe a Stacks transaction, might be something cool we can do there with @aibtcdev tooling!

sips/sip-02x/sip-02x-stacks-pay.md

friedger · 2025-03-07T11:03:52Z

How difficult is it to integrate into existing payment flows? E.g. compared to eth integration. Maybe something for the introduction.

flormpecasique · 2025-04-01T22:37:20Z

Hey Dan 👋

Awesome work on this! I wanted to share some thoughts based on my experience building Stacks Invoice Generator, where I tackled invoice generation for STX and Stacks tokens without smart contracts. One of the biggest challenges I faced was QR code functionality.

Initially, I wanted users to scan a QR code and have it automatically open their wallet (Xverse/Leather) with all payment details pre-filled—similar to Bitcoin or Ethereum payment URIs (e.g., bitcoin:address?amount=0.1). However, Stacks doesn’t currently support a universal payment link format, so I had to settle for QR codes that only contain the recipient’s address, requiring users to manually enter the amount and memo.

I believe adding universal payment links for STX and tokens (e.g., stackspay:stx1abc...xyz?amount=100&token=STX&memo=Invoice123) would be a game-changer for the ecosystem. It would:
✅ Enable seamless integration between wallets and apps.
✅ Improve the user experience by eliminating manual data entry.
✅ Make STX payments feel as smooth as Lightning payments in Bitcoin.

Would love to hear your thoughts on this! Is this something that could fit into Stacks Pay?

dantrevino · 2025-04-02T19:42:37Z

Hey Dan 👋

Awesome work on this! I wanted to share some thoughts based on my experience building Stacks Invoice Generator, where I tackled invoice generation for STX and Stacks tokens without smart contracts. One of the biggest challenges I faced was QR code functionality.

Initially, I wanted users to scan a QR code and have it automatically open their wallet (Xverse/Leather) with all payment details pre-filled—similar to Bitcoin or Ethereum payment URIs (e.g., bitcoin:address?amount=0.1). However, Stacks doesn’t currently support a universal payment link format, so I had to settle for QR codes that only contain the recipient’s address, requiring users to manually enter the amount and memo.

I believe adding universal payment links for STX and tokens (e.g., stackspay:stx1abc...xyz?amount=100&token=STX&memo=Invoice123) would be a game-changer for the ecosystem. It would: ✅ Enable seamless integration between wallets and apps. ✅ Improve the user experience by eliminating manual data entry. ✅ Make STX payments feel as smooth as Lightning payments in Bitcoin.

Would love to hear your thoughts on this! Is this something that could fit into Stacks Pay?

QR codes are a core part of the experience i the proposal. Check out https://stackspay.org/ and the Merchant Section in the spec for details. The encoding also has the benefit of providing checksum so that users (stackpay parsers) can ensure that the QR codes have not been tampered with.

friedger

How could an invoice be defined where the merchant requests an amount in BTC and wants to receive the amount on the stacks chain? Or the amount is in usdc and the merchant wants to receive usdcx on the stacks chain?

Do we make an explicit mention of chain id? Default to mainnet if omitted? recipient, token and contract MUST be on the same network (or compatible with bridged tokens, see above)

friedger · 2026-02-05T06:34:46Z

sips/sip-02x/sip-02x-stacks-pay.md

+
+| Name | Type / Format | Description |
+|------|---------------|-------------|
+| `recipient` | Stacks c32-address | Address that ultimately receives the payment. |


recipient could be also a contract (or in the future a bitcoin address #219)

friedger · 2026-02-05T06:35:19Z

sips/sip-02x/sip-02x-stacks-pay.md

+| Name | Type / Format | Description |
+|------|---------------|-------------|
+| `recipient` | Stacks c32-address | Address that ultimately receives the payment. |
+| `token` | **STX** \| SIP-010 contract address (`SP….<contract>`) | Asset used to pay.  When omitted wallets **MUST** default to **STX**. |


The token should contain the asset as well so that post conditions can be created easily, in a similar syntax as used in the in-contract post conditions.

friedger · 2026-02-05T06:39:40Z

sips/sip-02x/sip-02x-stacks-pay.md

+
+---
+
+### 3.3 `mint`


Why mint? It could also make sense to have a generic execute operation.

This operation can also make sense for depositing tokens into a vault.

friedger · 2026-02-05T06:40:26Z

sips/sip-02x/sip-02x-stacks-pay.md

+
+### 3.1 `support`
+
+Description of support operation here


Is Description of support operation here a TODO or a title

friedger · 2026-02-05T06:41:53Z

sips/sip-02x/sip-02x-stacks-pay.md

+## 7 Ratification Criteria
+
+1. SIP accepted by governance.  
+2. At least one reference implementation passes test-vectors.  


Where are the test-vectors defined?

friedger · 2026-02-05T06:43:28Z

sips/sip-02x/sip-02x-stacks-pay.md

+## 5 Security Considerations
+
+* **Post-conditions** – Wallets **SHOULD** add appropriate post-conditions
+limiting the transferred asset/amount.


Suggested change

limiting the transferred asset/amount.

limiting the transferred asset/amount provided in the parameters `amount` and `token`.

Extends NIP-57 (Lightning Zaps) to support on-chain payments using CAIP-358 (wallet_pay) alongside BOLT-11 invoices. Features: - payment_type tag (bolt11 | caip358) on kind 9734/9735 - CAIP-358 payment request/receipt in zap events - Stacks transfer types (sip10-transfer, stx-transfer) - CAIP-19 asset IDs for Stacks tokens (sBTC, STX) - Multi-chain payment options in single zap request - Full backward compatibility with NIP-57 Includes real-world example: 200 sats sBTC zap from cocoa007 to Stark Comet on Stacks mainnet with verified on-chain txids and the corresponding Nostr event published to relay.damus.io and nos.lol. References: - NIP-57: https://github.com/nostr-protocol/nips/blob/master/57.md - CAIP-358: https://standards.chainagnostic.org/CAIPs/caip-358 - SIP-029: stacksgov/sips#202 - sBTC zap spec: cocoa007/x402-nostr-relay#3

dantrevino · 2026-03-14T04:22:53Z

@friedger Valid question about cross-chain scenarios. Three perspectives:

1. Scope decision: This SIP intentionally focuses on Stacks-native payments (STX + SIP-010 tokens). Adding BTC/L2 bridging logic would significantly expand the spec into bridge routing, which is currently out of scope. Chain ID could be added as an optional parameter for future L2s, but mainnet should remain the default (omit = mainnet).

2. Cross-chain is a layer above: If a merchant wants to receive Stacks-denominated assets after a BTC payment, that's a bridge/service layer concern. The wallet pays what the invoice requests (BTC), the bridge converts it, the merchant receives on Stacks. The Stacks Pay URL should represent the payment request (what the payer sends), not the merchant's final receipt.

3. Token contracts handle this: For USDC → USDCx scenarios, the recipient and token contract are the authority. If recipient=SP...usdc-bridge and token=SP...usdc, the bridge contract handles the conversion. The spec doesn't need to know about bridging semantics—it just needs to pass the right address and token contract.

Concrete suggestion: Add a network parameter (optional, defaults to 'mainnet') with values like 'testnet', 'devnet' for test environments. Leave cross-chain bridging to the service layer—this spec stays focused on payment request encoding, not routing.

Worth adding a 'Future Work' section documenting these as out-of-scope with a note that bridge services can build on top of this.

Comment by Patient Eden (autonomous agent, cycle 15339)

dantrevino · 2026-03-14T06:11:43Z

Review of SIP-029 (Stacks Pay)

This is a solid proposal! A few suggestions to address the placeholder sections in Section 3:

3.1 `support` - Suggested description:

"A support operation enables tip/donation flows where the recipient requests support without specifying a fixed amount. Useful for content creators, open source projects, or any voluntary contribution scenario."

3.2 `invoice` - Suggested description:

"An invoice operation represents a payment request with fixed parameters (recipient, token, amount). Used for e-commerce, services, or any scenario requiring exact payment terms."

3.3 `mint` - Suggested description:

"A mint operation enables NFT minting flows by invoking a claim function on an NFT contract. The wallet address becomes the minter/receiver. Supports defacto standard contracts (e.g., Gamma) and limits attack surface versus arbitrary contract calls."

Other observations:

Section 4 (Custom Operations) is missing a number header - should be "4 Custom Operations" to match the outline
The Integration Simplicity section is great for developer adoption - consider moving it to the Introduction or Motivation section to strengthen the rationale

Overall excellent work on standardization! 🚀

Reviewed by Patient Eden (autonomous agent, cycle 15355)

dantrevino added 5 commits September 26, 2024 10:10

add sip

a67e190

update per recommendations

8ca9162

clarify purpose, clarify default functions for mint and transfer

cfcd542

clarify transfer default, code layout

fa5f8ba

Merge branch 'main' into feature/stacks-pay

6866f12

dantrevino mentioned this pull request Dec 2, 2024

Boom Payment Request Standard - Dan T. stacksgov/decentralized-grants#8

Open

dantrevino changed the title ~~Feature/stacks pay~~ Stacks Pay: A Payment Request Standard for Stacks Blockchain Payments Dec 2, 2024

kyranjamie reviewed Dec 4, 2024

View reviewed changes

sips/sip-02x/sip-02x-stacks-pay.md Outdated Show resolved Hide resolved

sips/sip-02x/sip-02x-stacks-pay.md Outdated Show resolved Hide resolved

whoabuddy reviewed Dec 13, 2024

View reviewed changes

dantrevino added 3 commits June 8, 2025 02:52

resolve comments, clarify encoding process, add appendix

dfb954c

learned how to do md urls

d5d7991

Added token and amount specification and minor cleanup

915ccf0

friedger reviewed Feb 5, 2026

View reviewed changes

cocoa007 mentioned this pull request Feb 20, 2026

feat: sBTC zaps via Stacks Pay payment requests (NIP-57 alternative) cocoa007/x402-nostr-relay#3

Open

	limiting the transferred asset/amount.
	limiting the transferred asset/amount provided in the parameters `amount` and `token`.


		---

		### 3.3 `mint`

Conversation

dantrevino commented Dec 2, 2024

Uh oh!

binxbrigandine commented Dec 2, 2024

Uh oh!

markmhendrickson commented Dec 4, 2024

Uh oh!

kyranjamie left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

whoabuddy left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

friedger commented Mar 7, 2025

Uh oh!

flormpecasique commented Apr 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dantrevino commented Apr 2, 2025

Uh oh!

friedger left a comment

Choose a reason for hiding this comment

Uh oh!

friedger Feb 5, 2026

Choose a reason for hiding this comment

Uh oh!

friedger Feb 5, 2026

Choose a reason for hiding this comment

Uh oh!

friedger Feb 5, 2026

Choose a reason for hiding this comment

Uh oh!

friedger Feb 5, 2026

Choose a reason for hiding this comment

Uh oh!

friedger Feb 5, 2026

Choose a reason for hiding this comment

Uh oh!

friedger Feb 5, 2026

Choose a reason for hiding this comment

Uh oh!

dantrevino commented Mar 14, 2026

Uh oh!

dantrevino commented Mar 14, 2026

3.1 support - Suggested description:

3.2 invoice - Suggested description:

3.3 mint - Suggested description:

Other observations:

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

flormpecasique commented Apr 1, 2025 •

edited

Loading

3.1 `support` - Suggested description:

3.2 `invoice` - Suggested description:

3.3 `mint` - Suggested description: