Take crypto on CoinPay, set up in one pass. The onboarding behind pay.agent and every fleet site launch.
One engine, idempotent (run it twice, it finds what it made):
- payout addresses on the account (optional)
- a business, found by name or made
- the account's payout wallets copied into it
- its webhook pointed where you say, and the secret
- which coins it can be paid in now
npx @profullstack/coinpay-onboard site example.agent --webhook https://example.agent/hooks/coinpayLogs in as the merchant (COINPAY_EMAIL + COINPAY_PASSWORD, else the
profullstack-private-secrets--prod vault), then writes COINPAY_API_URL,
COINPAY_BUSINESS_ID, COINPAY_API_KEY and COINPAY_WEBHOOK_SECRET into the
site's logicsrc vault (profullstack/example-agent--prod). --no-vault prints
them instead.
import { CoinPay, onboard, verifyWebhook } from '@profullstack/coinpay-onboard'
import { authorizeUrl, exchangeCode, pkce, refresh } from '@profullstack/coinpay-onboard/oauth'
// 1. send them to CoinPay (scopes: openid profile email wallet:read merchant)
const { verifier, challenge } = pkce()
redirect(authorizeUrl({ clientId, redirectUri, state, challenge }))
// 2. back with ?code=: tokens (1 h), refresh token (30 d, single-use: keep the newest)
const tokens = await exchangeCode({ code, verifier, clientId, redirectUri })
// 3. everything they need, in one call
const coinpay = new CoinPay({ token: tokens.accessToken })
const ready = await onboard(coinpay, { businessName: 'pay.agent/alice', webhookUrl: 'https://pay.agent/hooks/coinpay' })
// 4. take a payment
const payment = await coinpay.createPayment({ businessId: ready.business.id, amountUsd: 5, currency: 'usdc_sol' })
// payment.address, payment.amountCrypto, payment.expiresAt
// 5. hear about it
verifyWebhook(rawBody, req.headers['x-coinpay-signature'], ready.webhookSecret!)Confidential client, auth code + PKCE S256 + state + nonce, scopes openid profile email.
import { authorizeUrl, finishSignIn, pkce, randomToken, sameState, SIGN_IN_SCOPES } from '@profullstack/coinpay-onboard/oauth'
// start: keep verifier, state and nonce server-side (or in a signed httpOnly cookie)
const { verifier, challenge } = pkce()
const state = randomToken(), nonce = randomToken()
redirect(authorizeUrl({ clientId, redirectUri, state, nonce, challenge, scopes: SIGN_IN_SCOPES }))
// callback: state must match, then code exchange + id_token checks (iss, aud, exp, nonce) + userinfo
if (!sameState(saved.state, query.state)) throw new Error('bad state')
const { sub, email, name } = await finishSignIn({ code, verifier, nonce, clientId, clientSecret, redirectUri })STANDING rule: bind the local account to sub only. The CoinPay email is unverified
contact information: never sign into an existing account because the email matches,
never store it as a verified account email, never grant anything from it. Link CoinPay
to an existing account only while the user is signed in to it.
Applications can use @profullstack/coinpay-onboard/identity for consistent
account-link policy. A CoinPay identity may be linked by its owner to multiple
local accounts; a local account may still link only one CoinPay identity. If a
CoinPay sign-in maps to multiple local accounts, use resolveCoinPaySignIn() to
present an authenticated account chooser instead of choosing an account implicitly.
A user who deposits $99 into their own CoinPay wallet gets a free month on every
Profullstack property. CoinPay reports it as a pass claim on userinfo (scope openid).
Give full/paid access while it is active, then fall back to your normal crypto checkout.
import { hasPassAccess, passFromUserinfo, PASS_URL } from '@profullstack/coinpay-onboard'
import { finishSignIn } from '@profullstack/coinpay-onboard/oauth'
const { sub, pass } = await finishSignIn({ code, verifier, nonce, clientId, clientSecret, redirectUri })
if (pass.active) grantPaidAccess(sub, { until: pass.expiresAt }) // or hasPassAccess(userinfoBody)
else showCheckout({ orGetAPass: PASS_URL }) // https://coinpayportal.com/passpassFromUserinfo(claims, now?) is defensive: a missing claim (older CoinPay, failed
lookup), garbage input, or active: true with a past or missing expires_at is
{ active: false }. Re-check on each sign-in or token refresh; the pass expires.
The buyer picks the method on CoinPay's page; the site never builds a chain picker.
import { CoinPay, readWebhook, verifyWebhook } from '@profullstack/coinpay-onboard'
const coinpay = new CoinPay({ token: process.env.COINPAY_API_KEY }) // the business cp_live_ key
const session = await coinpay.createCheckoutSession({
amount: 19, // USD
description: 'Pro plan, 1 month',
customerEmail: user.email, // required
accountId: user.id, // required; use the email for guests
property: 'example.com', // the site hostname
metadata: { plan: 'pro' },
successUrl: 'https://example.com/billing?session={CHECKOUT_SESSION_ID}',
cancelUrl: 'https://example.com/pricing',
})
redirect(session.url) // https://coinpayportal.com/checkout/cs_...
// webhook
if (!verifyWebhook(rawBody, req.headers['x-coinpay-signature'], secret)) return 401
const event = readWebhook(JSON.parse(rawBody))
if (event.paid) grant(event.accountId, event.metadata, event.checkoutSessionId)readWebhook reads the nested data (the top-level id is the event, not the
payment), treats payment.confirmed and payment.forwarded as paid, and a
PayPal capture (payment.confirmed, status completed, method: 'paypal')
the same. coinpay.checkoutSession(id) polls a session; with the business key
it carries the payer fields and payment ids. With an OAuth token, pass
businessId.
coinpay-onboard site <name> --webhook URL launch step, keys into the vault
coinpay-onboard pay <business-id> <usd> [coin]
coinpay-onboard status <payment-id>
coinpay-onboard coins
coinpay-onboard mcp claude mcp add coinpay-onboard -- npx @profullstack/coinpay-onboard mcp
MIT