Payment Pool

The payment pool is the core routing mechanism of surstrom. Relays opt their providers into the pool to receive payments.

How It Works

  1. Relay toggles a provider into the pool via the dashboard
  2. The provider becomes available for payment routing
  3. When a Client creates a payment, surstrom selects from pool providers
  4. Selection uses LRU routing — the provider that received a payment longest ago is chosen first
  5. After processing, the provider moves to the back of the queue

Joining the Pool

Requirements before joining:

RequirementDescription
API key validRestricted key must have correct provider permissions
Publishable key setRequired for the frontend payment form
Embed URL configuredThe page URL where SDK is installed
SDK verifiedScript tag detected and iframe embedding allowed
Wallet balance sufficientMinimum 10 USDC available (balance minus pending)
No pending withdrawalsCannot join pool while a withdrawal is processing

Toggle your provider into the pool from the provider settings page. The system runs a final check on Alchemy webhook subscriptions before activating.

LRU Routing

Providers are sorted by lastPayment timestamp (ascending). The provider with the oldest lastPayment is selected first. This ensures:

  • Even distribution of payments across all providers
  • No single provider gets overloaded
  • New providers get immediate payments

Cross-Currency Fallback

If no provider matches the exact currency of a payment, surstrom attempts cross-currency matching:

  1. Only triggered when zero exact-currency providers are available
  2. Find providers with a different native currency that meet all other criteria
  3. Look up exchange rates from the platform (not the provider)
  4. Convert the payment amount to the provider's currency
  5. Route the payment with the exchangeRoute metadata attached

The exchangeRoute object in the response includes: original currency, target currency, exchange rate, original amount, and converted amount.

Leaving the Pool

When you toggle a provider out of the pool:

  • No new payments are routed to that provider
  • Existing in-progress payments continue to completion
  • Alchemy webhook subscriptions are cleaned up

You cannot withdraw while any of your providers are in the pool. Remove all providers from the pool before withdrawing.

Automatic Removal

A provider is automatically removed from the pool if:

  • The API key becomes invalid (revoked, expired)
  • SDK verification fails during payment routing
  • The provider loses card_payments capability
  • Balance drops too low to cover settlements

For a full interactive explanation of the pool mechanics, see Pool explained.