ar.io DocumentationGateway Providers
Gateway providers supply the list of gateways for routing. By default, createWayfinderClient uses a cached TrustedPeersGatewaysProvider.
| Provider | Description | Use Case |
|---|---|---|
NetworkGatewaysProvider | Returns gateways from AR.IO Network | Leverage AR.IO Network with quality filtering |
TrustedPeersGatewaysProvider | Fetches from trusted gateway's peers | Dynamic gateway discovery (default) |
StaticGatewaysProvider | Returns a static list of gateways | Testing or specific gateways |
SimpleCacheGatewaysProvider | In-memory caching wrapper | Reduce API calls (used by default) |
LocalStorageGatewaysProvider | Browser localStorage caching | Persistent caching (used by default in browsers) |
CompositeGatewaysProvider | Chains multiple providers with fallback | Maximum resilience with multiple sources |
NetworkGatewaysProvider
Returns a list of gateways from the ARIO Network based on on-chain Gateway Address Registry. You can specify on-chain metrics for gateways to prioritize the highest quality gateways. This requires installing the @ar.io/sdk package and importing the ARIO object.
import { NetworkGatewaysProvider } from '@ar.io/wayfinder-core';
import { ARIO } from '@ar.io/sdk';
const gatewayProvider = new NetworkGatewaysProvider({
ario: ARIO.mainnet(),
sortBy: 'operatorStake',
sortOrder: 'desc',
limit: 10,
filter: (gateway) => gateway.status === 'joined',
});TrustedPeersGatewaysProvider
Fetches a dynamic list of trusted peer gateways from an AR.IO gateway's /ar-io/peers endpoint. This provider is useful for discovering available gateways from a trusted source.
import { TrustedPeersGatewaysProvider } from '@ar.io/wayfinder-core';
const gatewayProvider = new TrustedPeersGatewaysProvider({
trustedGateway: 'https://turbo-gateway.com',
});CompositeGatewaysProvider
Chains multiple gateway providers together, trying each in sequence until one succeeds. This is useful for building resilient gateway discovery with fallbacks.
How it works:
- Tries each provider in the order they're provided
- If a provider returns a non-empty list of gateways, those gateways are used
- If a provider throws an error or returns an empty list, moves to the next provider
- If all providers fail, throws an error
import {
CompositeGatewaysProvider,
NetworkGatewaysProvider,
StaticGatewaysProvider,
TrustedPeersGatewaysProvider,
} from '@ar.io/wayfinder-core';
import { ARIO } from '@ar.io/sdk';
// Example: Network-first with static fallback
const gatewayProvider = new CompositeGatewaysProvider({
providers: [
// Try fetching from AR.IO network first
new NetworkGatewaysProvider({
ario: ARIO.mainnet(),
sortBy: 'operatorStake',
limit: 10,
}),
// Fallback to trusted peers if network fetch fails
new TrustedPeersGatewaysProvider({
trustedGateway: 'https://turbo-gateway.com',
}),
// Final fallback to static list
new StaticGatewaysProvider({
gateways: ['https://turbo-gateway.com', 'https://g8way.io'],
}),
],
});How is this guide?