@fractalai/pay

FractalPay AaaS — TypeScript SDK for the post-quantum, AI-verified, multi-chain payment gateway as a service.

Stripe-shaped API. Nine blockchains (8 EVM + Stellar) native. Cryptographic VAID-1 attestation on every payment. 0.618% fee instead of 2.9% + 30¢.

Companion to the Python SDK — same API surface, same naming, switch languages without retraining.

Install

npm install @fractalai/pay
# or
pnpm add @fractalai/pay
# or
yarn add @fractalai/pay

Requires Node 18+. Zero dependencies — uses native fetch and crypto.

Quickstart — receive a payment in 5 lines

import { FractalPay } from '@fractalai/pay';

const fp = new FractalPay();

const intent = await fp.intents.create({
  amount: '100.00',
  currency: 'USDC',
  recipientAddress: '0xYourWalletOnBase',
  recipientChain: 'base',
  description: 'Pro plan — monthly',
  callbackUrl: 'https://your-app.com/webhooks/fractalpay',
});

console.log(`Send your customer to: ${intent.webUrl}`);
// → https://fractalai.net.co/pay/{intent.id}

That's it. The customer lands on a hosted checkout page, pays in their wallet, your webhook fires when the payment is confirmed on-chain.

Why this exists

| | Stripe | Coinbase Commerce | FractalPay | |---|---|---|---| | Fee per tx | 2.9% + 30¢ | 1.0% | 0.618% (φ⁻¹) | | Chains supported | 0 (card only) | 4 | 9 (8 EVM + Stellar) | | Post-quantum signatures | ❌ | ❌ | ✅ CRYSTALS-Dilithium | | Cryptographic proof per payment | ❌ | ❌ | ✅ VAID-1 attestation | | Open source | ❌ | ❌ | ✅ Apache-2.0 |

Verify an incoming webhook (Express example)

import express from 'express';
import { verifyWebhook, SignatureVerificationError } from '@fractalai/pay';

const app = express();

// IMPORTANT: use raw body, not express.json() — re-serializing breaks the signature
app.post('/webhooks/fractalpay',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    try {
      const event = verifyWebhook({
        payload: req.body, // Buffer
        signature: req.header('x-fractalpay-signature'),
        secret: process.env.FRACTALPAY_WEBHOOK_SECRET!,
      });

      if (event.type === 'payment.completed') {
        fulfillOrder(event.intent.metadata?.orderId);
      }
      res.status(200).send();
    } catch (err) {
      if (err instanceof SignatureVerificationError) {
        return res.status(401).send();
      }
      throw err;
    }
  }
);

Query an intent

const intent = await fp.intents.retrieve('intent_abc123');
console.log(intent.status);
// 'created' | 'detecting' | 'confirming' | 'bridging' | 'completed' | 'expired' | 'failed' | 'refunded'

if (intent.status === 'completed') {
  console.log(`Settled: ${intent.settledAmount} ${intent.currency} on ${intent.recipientChain}`);
  console.log(`Payer: ${intent.payerAddress}`);
  console.log(`Tx hash: ${intent.txHash}`);
}

List intents

// All recent
const intents = await fp.intents.list({ limit: 100 });
for (const intent of intents) {
  console.log(intent.id, intent.amount, intent.status);
}

// Only completed
const completed = await fp.intents.list({ status: 'completed', limit: 50 });

Multi-chain payment routing

Your customer can pay from ANY of the 9 supported chains; FractalPay handles the routing and bridges to your settlement chain.

const intent = await fp.intents.create({
  amount: '500.00',
  currency: 'USDC',
  recipientAddress: '0xMyBaseWallet',
  recipientChain: 'base',       // You want USDC on Base
  // Customer can pay from: ethereum, polygon, arbitrum, stellar, etc.
});

// `intent.suggestedChains` lists the chains the customer can use.

Typed errors

All errors extend FractalPayError. Use instanceof checks for fine-grained handling:

import {
  AuthenticationError,
  InvalidRequestError,
  RateLimitError,
  APIConnectionError,
  APIError,
} from '@fractalai/pay';

try {
  await fp.intents.create({ ... });
} catch (err) {
  if (err instanceof RateLimitError) {
    await sleep(2000);
    // retry
  } else if (err instanceof InvalidRequestError) {
    console.error('bad input:', err.errorCode);
  } else if (err instanceof APIConnectionError) {
    // network problem, retryable
  } else if (err instanceof APIError) {
    // 5xx, retryable
  } else {
    throw err;
  }
}

License

• This SDK: Apache-2.0 (see LICENSE)
• The FractalPay API and protocol: same license, open-source at github.com/johnInarti/FRACTAL-AI

Resources

• API reference
• Python SDK (same API surface)
• VAID-1 spec
• Issues (label fractalpay)