Skip to main content
Glama
coinpay-onboard

coinpay-onboard

by profullstack

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

Related MCP server: Yolfi MCP Server

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

Sign in with CoinPay on a relying party

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.

Profullstack Pass

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/pass

passFromUserinfo(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.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI coding agents to add stablecoin checkout, payment links, payment status checks, webhook verification, and webhook-based entitlement logic to applications. It also provides tools for workspace registration, settlement and webhook configuration, paylink creation, and crypto payment status checks.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI coding agents and MCP hosts to register a workspace, create stablecoin checkout and payment links, configure webhooks, verify crypto payment status, and add webhook-based access logic to applications.
      -
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI coding agents to add stablecoin checkout, payment links, payment status checks, webhook verification, and webhook-based access logic to applications. It provides tools for registering workspaces, configuring settlement wallets and webhooks, creating paylinks, and verifying crypto payment status.
      MIT