A standard for enabling one-interaction cryptocurrency payment flows across wallets and dapps, allowing all payment information to be transmitted in a single round-trip.
This CAIP standardizes a wallet <> dapp JSON-RPC method wallet_pay for more efficient communication about the purchase intent from the dapp to the wallet.
The method allows merchants to specify payment requirements enabling wallets to handle payment execution with minimal user interaction.
Current cryptocurrency payment experiences are either error-prone (manual transfers, address QR codes) or overly complex, often requiring multiple user interactions. In addition to this, different payment providers implement different payment experiences, creating confusion.
Solutions like ethereum: (ERC-681) or bitcoin: url are ecosystem-specific and have not historically gotten sufficient support from the wallets. They tend to rely on a QR code scan as well, which means that they can't be batched as part of a connection-flow using protocols like WalletConnect.
By standardizing the payment experience on both the application and wallet side, we reduce user errors and enable payments in as few interactions as possible, lowering friction across crypto payments.
The method transmits all the acceptable payment requests so the wallet can pick the most optimal one based on the assets that user has in the account and the wallet's capabilities.
wallet_payThe following request parameters are defined for version=1 as:
version - this field is an integer and MUST be present to define which of the following parameters are optional or required.orderId - this field MUST uniquely identify an order which this payment request is linked to and MUST NOT be longer than 128 characters. It does not require global uniqueness, but it's RECOMMENDED to use a UUIDv4 if global uniqueness is necessary.expiry - this field MUST be a UNIX timestamp (in seconds) after which the payment request is considered expired. It SHOULD use an expiry of at least 5 minutes (300 seconds).paymentOptions - this field MUST be an array of PaymentOption objects with at least one entry. Each element in the array represents a payment option the wallet may choose to complete the payment, each with independent parameters.Note: Merchants CAN signal PaymentOption preference by ordering the paymentOptions array. JSON-RPC guarantees array order, but wallets are NOT REQUIRED to honor it. Wallets MAY offer swaps or bridges to help users match the merchant’s preferred option.
For PaymentOption parameters these are defined for version=1 as:
asset - this field MUST follow the assetId CAIP-19 spec which also includes the CAIP-2 chainId prefix.amount - this field MUST be a Hex string representing the amount in the smallest denomination of its asset.recipient - this field MUST be a chain-specific address present in the chain referred in the asset field.types - this field MUST be an array of strings defining different transfer authorization types.The exclusive list of Transfer Types supported in version=1 are the following:
native-transfer - this is used when a native token is being used as a PUSH payment (eg. ETH, SOL).erc20-transfer - this is used when an ERC-20 transfer is being used as a PUSH payment.erc20-approve - this is used when an ERC-20 allowance is approved to be used as a PULL payment.erc2612-permit - this is used when a ERC-2612 permit message is being used as a PULL payment.erc3009-authorization - this is used when a ERC-3009 authorization message is being used as a PULL payment.spl-transfer - this is used when a SPL transfer is being used as a PUSH payment.spl-approve - this is used when a SPL delegation is being used as a PULL payment.NOTE:
Example Request:
The following response parameters are defined for version=1:
version - this field is an integer and MUST match the same value used in the request.orderId - this field is a string and MUST match the same valued used in the request.payment - this field is a PaymentOption object and describes which option was used to fulfill this request and MUST match one of the provided options in the request.receipt - this field is a TransferReceipt object and will include the transfer type used and corresponding data which MUST not be empty.Example Response:
The wallet_pay method MUST be idempotent for the same orderId as this ensures robustness in case of connection failures or timeout scenarios:
orderId has already been completed successfully, the wallet MUST return the original PayResult without executing a new paymentorderId is currently pending, the wallet SHOULD return the result of the original payment attemptorderId previously failed, the wallet MAY attempt it again or return the same error.If the payment process fails, the wallet MUST return an appropriate error message:
The wallet MUST use one of the following error codes when the pay request fails:
If a wallet does not support the wallet_pay method, it MUST return an appropriate JSON-RPC error with code -32601 (Method not found).
Example error response:
This specification evolved through multiple iterations to address fundamental usability issues in cryptocurrency payment flows. Initial exploration began as a CAIP alternative to ERC-681/Solana Pay, but analysis of existing payment service provider (PSP) implementations revealed significant friction in current user experiences.
Existing cryptocurrency payment flows typically require users to:
This multi-step process creates excessive friction, often requiring 4-6 user interactions for a simple payment.
The wallet_pay method addresses these limitations by:
An intermediate solution involved encoding multiple payment addresses in a single QR code, allowing merchants to present all payment options simultaneously. However, this approach proved impractical for dapp implementations because:
TODO
wallet_pay does not try to address various cases of merchant fraud that end-users are exposed to today.
Specifically it does not try to tackle merchant fraud insurance in case the sold good is not delivered.
It also does not attempt to provide dispute functionality. These present ideas for future work.
Wallet addresses were intentionally omitted both for UX simplicity and to improve privacy.
By not requiring the user’s wallet address, this API can be implemented without first requesting a cross-origin identifier that could link a user’s activity across sites. Since the wallet address is not needed, the wallet may determine which address to use for the payment.
This design also supports use cases where payments originate from an address different from the user's primary account such as sponsored transactions, delegated or session-based accounts, or orchestration flows where the user controls multiple accounts.
Relying on payment requests rather than fixed wallet addresses provides greater flexibility and future-proofing. Wallets may automatically choose the appropriate token or address, or allow the user to override defaults when multiple options are available.
Wallets are encouraged to use transaction-privacy protocols to avoid exposing payment behavior on-chain.
A complete privacy protocol prevents manual or automated analysis (e.g., via block explorers) from identifying either the sender, recipient, or other transaction metadata such as amount.
Sender privacy protects users from having their purchase history used to build behavioral profiles, while recipient (e.g., merchant) privacy prevents real-time business data from being revealed as “business intelligence".
Depending on the use case, either or both protections may be required to avoid undesirable externalities from on-chain payment records.
This method is backwards compatible through a dual-payload pattern. A merchant MAY send both a standard wallet-connection request and a wallet_pay request in parallel.
Wallets that support wallet_pay MUST respond only to the wallet_pay request and proceed with the simplified payment flow.
Wallets that do not support wallet_pay will ignore the unknown method and instead follow the legacy sequence:
This approach allows dapps to adopt wallet_pay without breaking compatibility for existing wallets.
Copyright and related rights waived via CC0.