Payments SDK
@0xcurvy/payments-sdk is the TypeScript package shops and APIs use to accept Curvy payments. It is not the wallet SDK.
| Package | Audience | What it does |
|---|---|---|
@0xcurvy/curvy-sdk | Wallets and private-balance apps | Deposit, aggregate, transfer, withdraw, recovery |
@0xcurvy/payments-sdk | Merchants and checkout | Create signed payment requests, verify them, confirm payments on-chain |
A payment is confirmed when on-chain evidence matches the payment reference for that checkout - not when a browser or facilitator returns a transaction hash alone.
Payment reference
Each payment request includes a fresh payment reference: ephemeralKeyX and ephemeralKeyY from the derived request. Store these values when you create the request; pass them to verifyPayment when confirming the shield.
Do not put your payment reference in the signed checkout package. Curvy confirms the reference on chain; you connect it back to your own commerce identifiers in your application.
Products that use this package
- Human checkout — customer pays on Curvy’s hosted payment page; your backend creates and signs the deposit request.
- Agent / x402 — shopper uses a standard x402 client; resource server uses Payments SDK against Curvy’s facilitator.
You do not need Curvy spending or viewing keys on the shop or API server. Public receiving keys plus (for checkout) a request signing key are enough to accept money.
Package layout
| Entry point | Runtime | Responsibility |
|---|---|---|
@0xcurvy/payments-sdk | Browser and Node | Browser-safe convenience barrel |
@0xcurvy/payments-sdk/intent | Browser and Node | Parse, sign, and verify payment requests |
@0xcurvy/payments-sdk/transport | Browser and Node | Fragment encode/decode and checkout URLs |
@0xcurvy/payments-sdk/chain | Browser and Node | Portal prediction and payment verification |
@0xcurvy/payments-sdk/contracts | Browser and Node | Payment contract ABIs |
@0xcurvy/payments-sdk/merchant/keys | Browser and Node | Build and parse /.well-known/curvy-payments.json |
@0xcurvy/payments-sdk/merchant | Node only | initialize, createPaymentRequest |
The request signing key and @0xcurvy/rs-core-wasm stay on the backend. Checkout pages import only the browser-safe entry points.
Documentation
- Getting started — install and create your first signed checkout URL
- Human checkout — request fields, well-known signers, return URL
- x402 — exact rail roles and how to run merchant integrator tests
- Confirming payments — verify received payments
- API surface — exports by entry point
Related
- Wallet SDK — private balances and intents for end users
- Accepting payments (businesses) — product overview for shops
- Portals — how entry portals fit the human rail