Integration

Getting Started

Wayfinder Extension

The wayfinder-extension is a simple Chrome extension that supports the ar:// routing protocol and allows you to:

• Navigate ar:// URLs directly in your browser
• Configure routing strategies - Choose how requests are routed to gateways
• Set verification preferences - Control content verification levels
• Monitor gateway performance - See which gateways are serving your requests

No coding required - just install the extension and start browsing ar:// URLs!

Developer Integration Options

For developers who want to integrate Wayfinder into their applications:

Wayfinder Core

The wayfinder-core library is the core protocol implementation that accepts various configuration options for setting up Wayfinder. It provides:

• Gateway selection strategies - Choose how to route requests
• Content verification - Optionally verify content authenticity
• Telemetry collection - Understand performance vs arweave.net
• Custom configurations - Fine-tune behavior for your use case

Wayfinder React

Web developers will likely be interested in wayfinder-react, which provides:

• React Context Provider - Easy integration with React apps
• Custom hooks - Simplified data fetching and state management
• Component library - Pre-built UI components for common patterns
• TypeScript support - Full type safety out of the box

Common Integration Pattern: Preferred with Fallback

For most builds, teams use the "preferred with fallback" pattern. This routing strategy prioritizes your preferred gateway but automatically falls back to other gateways in the network if needed:

import { createWayfinderClient } from '@ar-io/wayfinder-core';
import { ARIO } from '@ar.io/sdk';

const wayfinder = new createWayfinderClient({
  ario: ARIO.mainnet(),
  verification: 'hash',
  routing: 'preferred',
  preferredGateway: 'arweave.net',
});

This pattern ensures:

1. Primary traffic goes to your preferred gateway (one you run or are delegated to)
2. Automatic failover if your gateway can't serve the data
3. Network resilience by finding another gateway that can serve the content

For detailed routing strategy options, see the routing strategies documentation.

Verification: Optional but Encouraged

While verification is optional, it's strongly encouraged when fetching from gateways:

import { createWayfinderClient } from '@ar-io/wayfinder-core';

const wayfinder = createWayfinderClient({
  //...other settings,
  verification: 'hash', // hash based verification
});

Verification ensures you're receiving authentic content regardless of which gateway serves it.

Telemetry for Performance Insights

Enable telemetry to understand how Wayfinder performs relative to arweave.net:

import { createWayfinderClient } from '@ar-io/wayfinder-core';

const wayfinder = createWayfinderClient({
  //...other settings,
  telemetry: {
      enabled: true,
      sampleRate: 0.1, // sample 10% of requests
      apiKey: 'your-api-key', // optional
      clientName: 'my-app',
      clientVersion: '1.0.0'
  }
});

This helps teams make data-driven decisions about gateway selection and optimization.

React Integration Example

Here's a complete example using wayfinder-react:

import { WayfinderProvider, FastestPingRoutingStrategy } from '@ar-io/wayfinder-react';
import { ARIO } from '@ar.io/sdk;

// Configure Wayfinder
const wayfinderConfig = {
  gatewaysProvider: new NetworkGatewaysProvider({
    ario: ARIO.mainnet(),
  }),
  routingSettings: {
    // use the fastest pinging strategy to select the fastest gateway for requests
    strategy: new FastestPingRoutingStrategy({
      timeoutMs: 1000,
    }),
  }
  verificationSettings: {
    enabled: false
  }
};

// Wrap your app
function App() {
  return (
    <WayfinderProvider config={wayfinderConfig}>
      <YourApp />
    </WayfinderProvider>
  );
}

// Use in components
function WayfinderImage({ txId }: { txId: string }) {
  const { resolvedUrl, isLoading, error } = useWayfinderUrl({ txId });

  if (error) {
    return <p>Error resolving URL: {error.message}</p>;
  }

  if (isLoading) {
    return <p>Resolving URL...</p>;
  }

  return (
    <img src={resolvedUrl} alt={txId} />
  );
}