Integration Guide

v3.0 — SDK + Automatic Settlement

Overview

Stratum handles settlement so you don't have to. Submit verified payments via the SDK or API. Stratum batches, nets, and settles USDC on-chain every 60 seconds. You get a txHash proving every payment settled.

Authentication

Get an API key at stratumx402.com/facilitators. Include it in all requests:

CopyX-API-KEY: sk_live_your_key

Quick Start

1Get your API key

Generate an API key instantly at stratumx402.com/facilitators. No approval required.

2Install the SDK

Copynpm install @v402valeo/facilitator

3Submit a payment

Copyconst { Stratum } = require('@v402valeo/facilitator');
const stratum = new Stratum({ apiKey: 'sk_live_...' });

// Solana payment:
await stratum.submit({
  from: 'agent_wallet_address',
  to: 'service_wallet_address',
  amount: '5000',
  chain: 'solana',
  reference: 'payment-001'
});

// Base payment (EVM addresses):
await stratum.submit({
  from: '0x4df375e577825ae021c1b44ba94F8CD84E59750c',
  to: '0xECa8FFA1134fda5e4042E25740DC02701d8Ed738',
  amount: '10000',
  chain: 'base',
  reference: 'payment-002'
});

Batch Submit (mixed chains)

Copy// Submit multiple payments across both chains in one call:
await stratum.submitBatch([
  { from: '4QWY4...', to: 'FjeQfz...', amount: '5000', chain: 'solana', reference: 'sol-001' },
  { from: '0x4df3...', to: '0xECa8...', amount: '10000', chain: 'base', reference: 'base-001' },
]);
// Up to 500 payments per call. Chains can be mixed freely.

4Check status

Copyconst result = await stratum.status('payment-001');
console.log(result.status);  // 'settled'
console.log(result.txHash);  // '4PxAjvFrj...'

API Reference

Base URL: https://gateway.stratumx402.com

Submit Payload

CopyPOST /v1/settle/submit
Content-Type: application/json
X-API-KEY: sk_live_your_key

{
  "payments": [
    {
      "from": "agent_wallet",
      "to": "service_wallet",
      "amount": "5000",
      "chain": "solana",
      "reference": "your-id"
    }
  ]
}

Single payment shorthand is also accepted — send from, to, amount directly without the payments array.

Status Response

Copy{
  "reference": "your-id",
  "status": "settled",
  "txHash": "4PxAjvFrjExWoKo...",
  "settledAt": "2026-03-10T03:30:58Z",
  "from": "agent_wallet",
  "to": "service_wallet",
  "amount": "5000",
  "chain": "solana"
}

Statuses: queued → batched → settled (or failed with error message).

Configuration

Supported Chains

Settlement Parameters

What Stratum Does Automatically

1. Creates destination token accounts if they don't exist
2. Compresses payments through multilateral netting
3. Executes USDC transfers on Solana and Base
4. Anchors Merkle proofs on-chain
5. Tracks per-payment status with txHash
6. Monitors settlement wallet balance
7. Recovers queued payments after restart

Limits & Safety

Verifying On-Chain

Every settled payment includes a txHash. Verify it independently:

Stratum also runs automatic post-settlement reconciliation every 5 minutes, verifying every settled transaction on-chain. Check reconciliation stats at GET /v1/settle/reconciliation.

For Sellers / API Providers

If you're a seller, you don't need the SDK. Register your service and USDC arrives automatically.

1Get an API key

Generate at stratumx402.com/facilitators.

2Register your service

CopyPOST https://gateway.stratumx402.com/admin/services
Content-Type: application/json
X-API-KEY: sk_live_your_key

{
  "slug": "my-api",
  "name": "My API",
  "walletAddress": "your_solana_wallet_address",
  "pricePerRequest": 5000
}

3Done

USDC arrives in your wallet every 60 seconds. No code changes needed. Your facilitator handles the rest.

Complete Integration Example

Here's the full middleware pattern — add this to your existing x402 payment handler:

Copyconst { Stratum } = require('@v402valeo/facilitator');
const stratum = new Stratum({ apiKey: 'sk_live_YOUR_KEY' });

app.use(async (req, res, next) => {
  const payment = req.headers['x-payment'];
  if (!payment) return res.status(402).json({ error: 'Payment required' });

  const verified = await verifyX402Payment(payment);
  if (!verified.valid) return res.status(402).json({ error: 'Invalid payment' });

  await stratum.submit({
    from: verified.agentWallet,
    to: verified.serviceWallet,
    amount: verified.amount,
    chain: verified.chain,
    reference: verified.paymentId
  });

  next();
});

That's 7 lines added to your existing middleware. Everything after stratum.submit() is automatic — netting, settlement, Merkle anchoring, status tracking.

Testing

Generate a test API key at stratumx402.com/facilitators. Check settlement status at stratumx402.com/console or the Explorer.