Curvy Docs

Appearance

Ask AI
Open in ChatGPTOpen in ClaudeView as Markdown

Payments SDK ​

@0xcurvy/payments-sdk is the TypeScript package shops and APIs use to accept Curvy payments. It is not the wallet SDK.

PackageAudienceWhat it does
@0xcurvy/curvy-sdkWallets and private-balance appsDeposit, aggregate, transfer, withdraw, recovery
@0xcurvy/payments-sdkMerchants and checkoutCreate signed payment requests, verify them, confirm payments on-chain

Preview

The API on these pages is a release candidate: @0xcurvy/payments-sdk@0.2.0-rc.3, published under npm's next tag. A plain install still gets 0.1.2 (latest), which exports an older verifyPayment from /chain. That version matches only the payment reference and returns a boolean, so do not use it to credit orders: install 0.2.0-rc.3 exactly. Curvy's hosted checkout page is the Curvy web app's /checkout route, https://app.curvy.box/checkout, and the SDK sends buyers there by default.

A payment counts as confirmed when an on-chain note matches the whole request you stored: the right owner, token and amount. A transaction hash sent by a browser or a facilitator does not confirm a payment by itself.

What a payment request contains ​

Each payment request gets a fresh one-time destination:

  • ownerHash: binds the note to your receiving identity, so only you can spend it.
  • the payment reference R (ephemeralKeyX, ephemeralKeyY) and a viewTag. Your wallet uses these to find the note later.
  • the token, amount and chainId you ask for, and an expiry.

Store each attempt on your server as one payment record: serializePaymentRecord turns the signed package, the block to scan from and the latest verification result into one versioned value, and parsePaymentRecord reads it back. Keep it whole; verifyPayment needs the whole request inside it. Anyone can put your R on a note they own, so matching R alone proves nothing.

Do not put your order id or any other commerce identifier in the signed checkout package. The package already contains R, and R is public: it is in the checkout URL fragment and on-chain. Link the request to your order in your own database.

Products that use this package ​

  1. Human checkout: the customer pays on Curvy’s payment page, and your backend creates and signs the request.
  2. Agent / x402: an agent pays per request, through Curvy’s x402 facilitator (exact; any other x402 v2 facilitator works too) or with a plain transfer (curvy-transfer); your resource server uses createX402Merchant with Curvy’s portal broadcaster, both preconfigured, and confirms each payment with the same verifyPayment check.

You do not need Curvy spending or viewing keys on the shop or API server. To accept money you need your public receiving keys, plus a request signing key for checkout. The web app's Payments setup gives the receiving keys as one value to copy, your public key for payments (CURVY_PAYMENTS_PUBLIC_KEY, in the .env block of step 3); see Receiving keys value.

Package layout ​

Entry pointRuntimeResponsibility
@0xcurvy/payments-sdkBrowser and NodeBrowser-safe convenience barrel
@0xcurvy/payments-sdk/intentBrowser and NodeParse, sign, and verify payment requests
@0xcurvy/payments-sdk/transportBrowser and NodeFragment encode/decode and checkout URLs (CURVY_CHECKOUT_URL)
@0xcurvy/payments-sdk/chainBrowser and NodeCurvy's built-in networks (CURVY_NETWORKS); receipt discovery hints (not payment proof); portal prediction, which is internal and unstable
@0xcurvy/payments-sdk/contractsBrowser and NodePayment contract ABIs
@0xcurvy/payments-sdk/economicsBrowser and NodeProtocol fee reads, quotes, and minimum amounts
@0xcurvy/payments-sdk/x402Browser and Nodex402 wire types, broadcaster and facilitator clients, payer helper, EIP-712 types, parsers, header codec
@0xcurvy/payments-sdk/x402/merchantNode onlycreateX402Merchant: charge agents per request over x402 (exact and curvy-transfer)
@0xcurvy/payments-sdk/merchant/keysBrowser and NodeBuild and parse /.well-known/curvy-payments.json; encode and parse the receiving-keys value; generateCheckoutSigningKey
@0xcurvy/payments-sdk/merchantNode onlyinitialize, createPaymentRequest, verifyPayment, serializePaymentRecord / parsePaymentRecord

The request signing key and @0xcurvy/rs-core-wasm stay on the backend. Checkout pages import only the browser-safe entry points. Payment verification is in /merchant because it recomputes the note commitment with rs-core.

Documentation ​