crumb-alpha-core

Low-level primitives for the Crumb SDK. Most users should use crumb-alpha-sdk instead — this package is for advanced use cases or building custom integrations.

Installation

pnpm add crumb-alpha-core

Wallet Utilities

Create and manage Ethereum wallets for signing payments.

import { createWallet, walletFromPrivateKey, deriveAddress } from 'crumb-alpha-core'

// Generate a new random wallet
const wallet = createWallet()
console.log(wallet.address)    // "0x..."
console.log(wallet.privateKey) // "0x..."

// Restore wallet from existing private key
const restored = walletFromPrivateKey('0xac09...')
console.log(restored.address)

// Derive address without creating a full wallet object
const address = deriveAddress('0xac09...')

createWallet(): CrumbWallet

Generates a new random private key and derives the corresponding address.

walletFromPrivateKey(privateKey: string): CrumbWallet

Creates a wallet object from an existing private key.

deriveAddress(privateKey: string): string

Derives the Ethereum address from a private key.

Error Handling

All Crumb errors use the CrumbError class with typed error codes.

import { CrumbError } from 'crumb-alpha-core'

try {
  await crumb.fetch(url, { maxPayment: 0.001 })
} catch (err) {
  if (err instanceof CrumbError) {
    switch (err.code) {
      case 'PRICE_EXCEEDED':
        console.log('Too expensive:', err.detail)
        break
      case 'INSUFFICIENT_BALANCE':
        console.log('Need more USDC')
        break
    }
  }
}

Error Codes

Code	Description
PRICE_EXCEEDED	Quoted price exceeds the maxPayment ceiling
INSUFFICIENT_BALANCE	Not enough USDC in Gateway
VERIFY_FAILED	Payment verification rejected by the facilitator
SETTLE_FAILED	Payment settlement failed
INVALID_402	Provider returned a malformed 402 response
NOT_402	Expected 402 status but got something else
PAYMENT_REJECTED	Provider rejected the payment header
WALLET_NOT_FOUND	No wallet configured
NETWORK_ERROR	Connectivity issue

Price Validation

import { checkPriceCeiling } from 'crumb-alpha-core'

// Throws PRICE_EXCEEDED if quoted > maxPayment
checkPriceCeiling('$0.05', 0.01) // throws!
checkPriceCeiling('$0.001', 0.01) // ok

Handles $ prefix automatically and ignores non-numeric values.

Balance Queries

import { getBalances } from 'crumb-alpha-core'

const wallet = { address: '0x...', privateKey: '0x...' }
const balances = await getBalances(wallet, 'arcTestnet')

console.log(balances.wallet)  // on-chain USDC balance
console.log(balances.gateway) // Gateway deposited balance

Settlement (Server-side)

For providers that need manual control over payment verification and settlement:

import { verifyPayment, settlePayment, verifyAndSettle } from 'crumb-alpha-core'

// Verify a payment payload
const verification = await verifyPayment(payload, requirements)

// Settle a verified payment
const settlement = await settlePayment(payload, requirements)

// Or do both in one call
const result = await verifyAndSettle(payload, requirements)
console.log(result.txHash)
console.log(result.payer)

Re-exports

crumb-alpha-core re-exports key types and utilities from @circle-fin/x402-batching:

• GatewayClient — Circle's buyer-side client
• CHAIN_CONFIGS — supported chain configurations
• GATEWAY_DOMAINS — Gateway API domains
• registerBatchScheme, BatchEvmScheme — advanced signing utilities
• BatchFacilitatorClient — server-side payment verification

Types

interface CrumbWallet {
  address: string
  privateKey: string
}

interface FetchOptions {
  method?: 'GET' | 'POST' | 'PUT' | 'DELETE'
  body?: unknown
  headers?: Record<string, string>
  maxPayment?: number
  metadata?: Record<string, string>
}

interface FetchResult<T = unknown> {
  data: T
  amount: bigint
  formattedAmount: string
  txHash: string
  status: number
}

interface SettlementResult {
  success: boolean
  txHash: string
  amount: string
  formattedAmount: string
  network: string
  payer?: string
  timestamp: string
}

type SupportedChainName = 'arcTestnet'