Facilitator Integration Guide

v1.0 — Settlement API

Overview

Stratum is a clearing layer that sits between AI agents and API providers. Instead of processing millions of individual payments, facilitators receive batched settlement instructions — typically 50 batch settlements instead of 500,000 individual ones.

As a facilitator, you:

1. Register a webhook endpoint with Stratum
2. Receive settlement batches when windows close (every 60 seconds)
3. Execute the USDC transfers on Solana and/or Base
4. Confirm execution back to Stratum

Authentication

Request an API key from Stratum with the facilitator role. Include it in all requests using either header format:

X-API-KEY: sk_live_your_key

// or

Authorization: Bearer sk_live_your_key

Quick Start

1Register your webhook

POST https://gateway.stratum.valeo.com/v1/settle/webhook
Content-Type: application/json
X-API-KEY: sk_live_your_key

{
  "url": "https://your-service.com/stratum/settle",
  "chains": ["solana", "base"],
  "secret": "whsec_your_webhook_secret"
}

The secret is used to sign webhook payloads via HMAC-SHA256 so you can verify authenticity.

2Receive settlement batches

When a settlement window closes, Stratum POSTs a batch payload to your webhook URL:

{
  "batchId": "batch-abc123",
  "windowId": "win-mm8jlizk-hrhj-1",
  "chain": "solana",
  "transfers": [
    {
      "from": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
      "to": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
      "amount": "470000",
      "chain": "solana"
    },
    {
      "from": "3kP9...",
      "to": "9WzD...",
      "amount": "120000",
      "chain": "solana"
    }
  ],
  "totalVolume": "1250000"
}

The X-Stratum-Signature header contains the HMAC-SHA256 signature for verification.

3Verify the webhook signature

const crypto = require('crypto');

const signature = req.headers['x-stratum-signature'];
const body = JSON.stringify(req.body);
const expected = crypto
  .createHmac('sha256', webhookSecret)
  .update(body)
  .digest('hex');

if (signature !== expected) {
  throw new Error('Invalid webhook signature');
}

4Execute transfers

For each transfer in the batch, execute the on-chain USDC transfer:

• Solana: SPL Token transferChecked for each item
• Base: ERC-20 USDC.transfer() for each item

Amounts are in USDC base units (6 decimals). 470000 = $0.47 USDC.

5Confirm execution

After executing all transfers, confirm back to Stratum with the transaction hashes:

POST https://gateway.stratum.valeo.com/v1/settle/batches/{batch_id}/confirm
Content-Type: application/json
X-API-KEY: sk_live_your_key

{
  "txHashes": ["5xKr3...", "9mWq7..."],
  "chain": "solana"
}

API Reference

Supported Chains

Batch Lifecycle

Settlement batches progress through the following states:

Error Handling

• Webhook delivery retries 3 times with exponential backoff (1s, 5s, 25s)
• If all retries fail, the batch stays pending and can be retrieved via GET /v1/settle/batches
• Failed transfers should be reported via the confirm endpoint with error details

Rate Limits

Default rate limit: 1,000 requests/minute per API key. Contact valeobank@gmail.com for higher limits.

Testing

• Use testnet chains (Solana Devnet, Base Sepolia) for integration testing
• Request a test API key with REQUIRE_API_KEYS=true
• The Stratum simulator generates test traffic for end-to-end testing: pnpm --filter @valeo/simulator start