FAQ
Settlement FAQ

Settlement FAQ

Common questions about how batch settlement works in Preimage Research.

General Questions

When will my payment settle on-chain?

Payments settle automatically when any of these conditions are met:

  • $1.00 accumulated (amount trigger)
  • 100 payments in queue (count trigger)
  • 1 hour since first payment (time trigger)
  • $10+ single payment (high-value trigger)
✓

Guaranteed: No payment waits longer than 1 hour. The time trigger ensures this.

Examples:

  • Low-frequency API (5 calls/hour @ $0.10): Settles hourly via time trigger
  • Medium-frequency API (30 calls/hour @ $0.05): Settles every 45-60 min via amount trigger
  • High-frequency API (1000 calls/hour @ $0.01): Settles every 5-10 min via count trigger
  • Enterprise API ($15/call): Settles immediately via high-value trigger

Can I see pending settlements?

Yes, you can check your settlement queue status via the API:

GET /settlements/status?wallet=0xYourWallet
 
Response:
{
  "wallet_address": "0xYourWallet",
  "accumulated_usdc": "0.75",
  "payment_count": 15,
  "first_payment_at": "2024-01-15T10:00:00Z",
  "age_seconds": 900,
  "estimated_settlement": "2024-01-15T11:00:00Z"
}

You can also view your settlement history:

GET /settlements/batches?wallet=0xYourWallet&limit=10
 
Response:
{
  "batches": [
    {
      "batch_id": 1234,
      "payment_count": 50,
      "total_usdc": "1.50",
      "gas_cost_usdc": "0.01",
      "tx_hash": "0xabc...",
      "trigger_type": "amount",
      "created_at": "2024-01-15T10:35:00Z",
      "confirmed_at": "2024-01-15T10:35:12Z"
    }
  ]
}

What happens if settlement fails?

Settlement failures are rare but can occur due to:

  • Network congestion
  • Buyer's wallet has insufficient USDC
  • Nonce already used (payment already settled)

Automatic Retry:

  • Failed settlements are retried with exponential backoff
  • System attempts up to 5 retries over 24 hours
  • You'll be notified if a batch repeatedly fails

What you get:

  • Service was already granted (user already accessed your API)
  • Receipt was already issued (proof of payment authorization)
  • Failed settlement tracked in your dashboard
💡

Risk Mitigation: Preimage Research optionally checks buyer USDC balances before accepting payments to minimize settlement failures.

Do I need to configure anything?

No configuration required! The system automatically optimizes based on your usage pattern:

  • Low-frequency APIs: Time trigger (hourly settlements)
  • Medium-frequency APIs: Amount trigger (every 45-60 min)
  • High-frequency APIs: Count trigger (every 5-10 min)
  • High-value APIs: High-value trigger (immediate)

All triggers work simultaneously - whichever condition is met first triggers the batch settlement.

How do I verify a settlement happened?

Method 1: Check the API

GET /settlements/batches?wallet=0xYourWallet&tx_hash=0xabc...

Method 2: Blockchain Explorer

For Base (mainnet):

https://basescan.org/tx/0xYourTxHash

For Base Sepolia (testnet):

https://sepolia.basescan.org/tx/0xYourTxHash

Look for the BatchSettled event in the transaction logs.

Method 3: Check Your Wallet

Your USDC balance will increase by the settled amount (minus gas, which Preimage Research covers).

Economics & Gas

How much does settlement cost?

Short Answer: Gas overhead is typically 0.5-1% of payment value.

Detailed Breakdown:

Batch SizeGas CostGas per PaymentOverhead @ $0.01Overhead @ $0.10
10 payments$0.005$0.00055%0.5%
50 payments$0.01$0.00022%0.2%
100 payments$0.01$0.00011%0.1%
✓

Key Point: Larger batches = lower gas overhead. The system automatically optimizes batch size based on your traffic.

Who pays the gas fee?

Preimage Research covers all gas fees for batch settlement.

The platform fee (2%) includes gas costs. You receive 98% of every payment with no additional charges.

What if gas prices spike?

Dynamic Adjustment:

  • System monitors Base network gas prices
  • If gas >$0.02, thresholds automatically increase:
    • Amount trigger: $1.00 → $2.00
    • Count trigger: 100 → 150
  • Ensures gas overhead remains under 2%

You'll still receive settlements within the guaranteed 1-hour window.

Technical Questions

What networks support batching?

Currently Supported:

  • ✅ Base (mainnet)
  • ✅ Base Sepolia (testnet)

Coming Soon:

  • 📋 Polygon (Q1 2025)
  • 📋 Ethereum mainnet (Q2 2025)

Network availability depends on gas costs and USDC availability.

How does batching work technically?

Step-by-Step:

  1. User signs payment (EIP-3009 authorization) during API call
  2. Instant verification (5-10ms cryptographic check)
  3. Service granted immediately
  4. Payment queued in settlement database
  5. Batch accumulates until trigger condition met
  6. Multicall contract executes all pending authorizations in ONE transaction
  7. Payments confirmed on-chain

Smart Contract:

// USDCBatchSettlement.sol
function batchTransferWithAuth(
    address[] calldata froms,      // All buyers
    address[] calldata tos,        // All providers
    uint256[] calldata values,     // All amounts
    // ... EIP-3009 signatures for each
) external {
    for (uint i = 0; i < froms.length; i++) {
        usdc.transferWithAuthorization(...);
    }
}

One blockchain transaction processes 100+ individual payments.

Is batching secure?

Yes. Security is identical to individual settlements:

Cryptographic Guarantees:

  • Each payment requires buyer's EIP-3009 signature
  • Signatures verified using standard Ethereum cryptography (secp256k1)
  • Nonces prevent replay attacks
  • Smart contract is permissionless and audited

What Batching Changes:

  • Timing: Payments settle in batches instead of individually
  • Gas efficiency: 50-100x reduction in gas costs

What Batching Doesn't Change:

  • Security: Same cryptographic guarantees
  • Custody: Still non-custodial (funds go directly to your wallet)
  • Verification: Same instant verification (5-10ms)
💡

The multicall contract is permissionless - anyone can call it. Signatures prove authorization, so there's no privileged access required.

Can I opt out of batching?

No. Batching is fundamental to the economics of micropayments on blockchain networks.

Without batching:

  • $0.01 payment = 50% gas overhead (unprofitable)
  • $0.001 payment = 500% gas overhead (impossible)

With batching:

  • $0.01 payment = 1% gas overhead (profitable)
  • $0.001 payment = 0.5% gas overhead (viable)

All payments are batched, but high-value payments ($10+) settle individually because gas is negligible relative to payment size.

Troubleshooting

My payment hasn't settled after 1 hour

Check these items:

  1. Verify payment was accepted:

    GET /payments/{paymentId}
# Should show: payment_status: "verified"

  2. Check settlement queue:

    GET /settlements/status?wallet=0xYourWallet
# Should show accumulated payments

  3. Check recent batches:

    GET /settlements/batches?wallet=0xYourWallet&limit=5
# Look for recent tx_hash

  4. Contact support if payment is verified but not in queue or batch history

Settlement failed - what do I do?

Automatic handling:

  • System automatically retries failed settlements
  • Exponential backoff: 1 min → 5 min → 15 min → 1 hour → 24 hours
  • You'll be notified after 3 failed attempts

Manual resolution:

  • Check buyer's USDC balance (they may need to top up)
  • Verify nonce wasn't reused
  • Contact support for manual settlement

Financial impact:

  • You already granted service (can't revoke)
  • Receipt already issued (proof of authorization)
  • Consider failed settlements in risk management
⚠️

Best Practice: Enable balance checks to minimize settlement failures. This verifies buyers have sufficient USDC before accepting payments.

How do I reconcile settlements for accounting?

Export settlement data:

GET /settlements/export?wallet=0xYourWallet&start=2024-01-01&end=2024-01-31&format=csv
 
CSV includes:
- batch_id
- payment_count
- total_usdc
- gas_cost_usdc (covered by Preimage)
- tx_hash (blockchain proof)
- trigger_type
- created_at
- confirmed_at

Reconciliation checklist:

  1. ✅ Verify total_usdc matches expected revenue
  2. ✅ Check all batches have confirmed_at timestamp
  3. ✅ Verify tx_hash on blockchain explorer
  4. ✅ Cross-reference with payment receipts
  5. ✅ Report any discrepancies to finance team

Best Practices

For Low-Frequency APIs (under 10 calls/hour)

✅ Expect hourly settlements via time trigger
✅ Gas overhead: 1-2% (acceptable for small batches)
✅ Cash flow: Hourly (predictable and consistent)

For Medium-Frequency APIs (10-100 calls/hour)

✅ Expect settlements every 45-60 minutes via amount trigger
✅ Gas overhead: 0.5-1%
✅ Cash flow: ~20 times per day

For High-Frequency APIs (100+ calls/hour)

✅ Expect settlements every 5-10 minutes via count trigger
✅ Gas overhead: 1% (optimal efficiency)
✅ Cash flow: Real-time (batches settle frequently)

For Enterprise APIs ($10+ per call)

✅ Expect immediate settlement via high-value trigger
✅ Gas overhead: under 0.1% (negligible)
✅ Cash flow: Immediate (no batching delay)

Getting Help

Documentation

Support

Emergency Issues

For critical settlement issues affecting cash flow:

FAQChangelog