Merchant Setup

This guide walks through setting up a merchant account on Crumb and accepting payments — both through the Crumb platform and via the SDK.

Register as a merchant

Via the Crumb app

1. Create an account at crumb-sepia.vercel.app (sign in with email via Privy)
2. Navigate to the Merchant section
3. Register with your merchant name (your Privy embedded wallet is used automatically)
4. You'll receive an API key (prefixed with crumb_) — copy it immediately, it is shown once and cannot be retrieved later. The key is stored as an HMAC-SHA256 hash, not in plaintext.

Via the API

curl -X POST https://www.crumb-sepia.vercel.app/api/merchants/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Store",
    "email": "merchant@example.com",
    "wallet_address": "0xYOUR_WALLET_ADDRESS",
    "callback_url": "https://your-server.com/webhooks/crumb"
  }'

Response:

{
  "merchant_id": "uuid",
  "api_key": "crumb_64hexchars...",
  "name": "My Store",
  "wallet_address": "0x..."
}

Accept payments with the SDK

The simplest way to accept payments is with createProvider from the SDK. It wraps Circle's payment middleware with an optional payment callback.

import express from 'express'
import { createProvider } from 'crumb-alpha-sdk'

const app = express()
app.use(express.json())

const provider = createProvider({
  sellerAddress: process.env.SELLER_ADDRESS,
  description: 'My API',
  onPayment: (payment) => {
    console.log(`Received ${payment.amount} from ${payment.payer}`)
    // Report to Crumb dashboard, update your DB, etc.
  },
})

// Free endpoint
app.get('/api/health', (req, res) => {
  res.json({ status: 'ok' })
})

// Paywalled endpoints — set any price
app.get('/api/data', provider.require('$0.001'), (req, res) => {
  res.json({ data: 'premium content' })
})

app.get('/api/premium', provider.require('$0.05'), (req, res) => {
  res.json({ data: 'very premium content' })
})

app.listen(3001)

Create payment links

For fixed-amount payments (e-commerce, invoices), create payment links via the API:

curl -X POST https://www.crumb-sepia.vercel.app/api/payments/create \
  -H "X-API-Key: crumb_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "5.00",
    "description": "Premium subscription",
    "redirect_url": "https://your-site.com/thank-you",
    "callback_url": "https://your-server.com/webhooks/payment"
  }'

Response:

{
  "payment_id": "pay_abc123",
  "payment_url": "https://www.crumb-sepia.vercel.app/pay/pay_abc123",
  "qr_data": "https://www.crumb-sepia.vercel.app/pay/pay_abc123",
  "amount": "5.00",
  "status": "pending",
  "expires_at": "2025-01-01T00:30:00Z"
}

Payment links expire after 30 minutes. Share the payment_url or render the qr_data as a QR code.

Embeddable checkout widget

Drop the Crumb widget onto any page for a "Pay with Crumb" button:

<div id="crumb-pay" data-payment-id="pay_abc123"></div>
<script src="https://www.crumb-sepia.vercel.app/widget.js"></script>

The widget opens a popup for the customer to complete payment. When payment succeeds, it dispatches a crumb:payment custom event on your page:

document.addEventListener('crumb:payment', (e) => {
  console.log('Payment complete:', e.detail)
  // Update your UI
})

Webhooks

When a payment is completed, Crumb sends a POST request to your callback_url:

{
  "payment_id": "pay_abc123",
  "status": "settled",
  "amount": "5.00",
  "payer_address": "0x...",
  "tx_hash": "0x...",
  "timestamp": "2025-01-01T00:05:00Z"
}

Webhooks are fire-and-forget with a 5-second timeout. Your server should respond with a 2xx status code.

API key security

API keys are hashed with HMAC-SHA256 before storage — the plaintext key is never stored in the database. Each key has a stored prefix (for lookup) and suffix (for display). In the dashboard, your key appears as crumb_...xxxx.

If you need a new key, use the Rotate Key button in your merchant settings. This immediately invalidates the old key and generates a new one. The new key is shown once — copy it before navigating away.

Merchant dashboard

The Crumb app provides a dashboard for merchants to:

• View payment history and revenue
• Filter payments by status (pending, paid, expired)
• Update merchant profile (name, callback URL, description)
• Toggle marketplace listing
• Rotate API keys

List on the marketplace

Set listed: true on your merchant profile to appear in the Crumb marketplace. Provide a description, category, pricing info, and tags to help agents discover your API.

curl -X PATCH https://www.crumb-sepia.vercel.app/api/merchants/YOUR_ID \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "listed": true,
    "description": "Real-time market data API",
    "category": "Finance",
    "api_url": "https://api.example.com",
    "pricing": "$0.001 per request",
    "tags": ["market-data", "finance", "real-time"]
  }'