@profullstack/coinpay-onboard

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):

1. payout addresses on the account (optional)
2. a business, found by name or made
3. the account's payout wallets copied into it
4. its webhook pointed where you say, and the secret
5. which coins it can be paid in now

At site launch

npx @profullstack/coinpay-onboard site example.agent --webhook https://example.agent/hooks/coinpay

Logs 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.

In an app (Sign in with CoinPay)

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!)

Hosted checkout (any coin or PayPal)

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.

CLI and MCP

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