wayfinder.request()

Fetch data from Arweave using the ar:// protocol with intelligent routing and verification. This method is a wrapper around the native Fetch API, providing the same interface with additional Wayfinder-specific functionality.

Syntax

const response = await wayfinder.request(input, init)

Parameters

  • input (string | URL | RequestInfo): The ar:// URL or standard fetch input
  • init (RequestInit & WayfinderRequestOptions, optional): Standard fetch options plus Wayfinder overrides

Wayfinder-Specific Options

interface WayfinderRequestOptions {
  verificationSettings?: {
    enabled?: boolean
    strategy?: VerificationStrategy
    strict?: boolean
    events?: WayfinderVerificationEventArgs
  }
  routingSettings?: {
    strategy?: RoutingStrategy
    events?: WayfinderRoutingEventArgs
  }
}

Returns

Type: Promise<Response>

Returns a standard Response object that can be processed with methods like response.text(), response.json(), response.blob(), etc.

Basic Usage

Fetching Different Data Types

import { Wayfinder } from '@ar.io/wayfinder-core'

const wayfinder = new Wayfinder({
  gatewaysProvider: gatewaysProvider,
})

// Fetch text content
const response = await wayfinder.request('ar://transaction-id')
const text = await response.text()

// Fetch JSON data
const jsonResponse = await wayfinder.request('ar://json-transaction-id')
const data = await jsonResponse.json()

// Fetch binary data (images, files, etc.)
const imageResponse = await wayfinder.request('ar://image-transaction-id')
const blob = await imageResponse.blob()
const imageUrl = URL.createObjectURL(blob)

Handling Unknown Data Types

When you don't know the MIME type in advance, check the Content-Type header to determine how to process the response:

const response = await wayfinder.request('ar://unknown-content-id')

// Check the content type
const contentType = response.headers.get('content-type')

let processedData
if (contentType?.includes('application/json')) {
  processedData = await response.json()
  console.log('JSON data:', processedData)
} else if (contentType?.includes('text/')) {
  processedData = await response.text()
  console.log('Text content:', processedData)
} else if (contentType?.startsWith('image/')) {
  processedData = await response.blob()
  const imageUrl = URL.createObjectURL(processedData)
  console.log('Image URL:', imageUrl)
} else {
  // Handle as binary data
  processedData = await response.arrayBuffer()
  console.log('Binary data size:', processedData.byteLength, 'bytes')
}

Custom Headers

You can pass custom headers with your requests using the standard fetch options:

// Basic custom headers
const response = await wayfinder.request('ar://transaction-id', {
  headers: {
    Accept: 'application/json',
    'User-Agent': 'MyApp/1.0.0',
    'X-Custom-Header': 'custom-value',
  },
})

// Authorization headers (if needed for specific gateways)
const response = await wayfinder.request('ar://transaction-id', {
  headers: {
    Authorization: 'Bearer your-token-here',
  },
})

// Content negotiation
const response = await wayfinder.request('ar://transaction-id', {
  headers: {
    Accept: 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
    'Accept-Language': 'en-US,en;q=0.5',
    'Accept-Encoding': 'gzip, deflate',
  },
})

Standard Fetch Options

Since wayfinder.request() is a wrapper around the native Fetch API, all standard fetch options are supported:

// Custom headers
const response = await wayfinder.request('ar://transaction-id', {
  headers: {
    Accept: 'application/json',
    'User-Agent': 'MyApp/1.0',
  },
})

// AbortController support
const controller = new AbortController()
setTimeout(() => controller.abort(), 5000)

const response = await wayfinder.request('ar://transaction-id', {
  signal: controller.signal,
})

// Caching options
const response = await wayfinder.request('ar://transaction-id', {
  cache: 'force-cache',
})

Wayfinder Override Settings

You can override the global Wayfinder configuration for individual requests:

Override Verification Settings

import { HashVerificationStrategy } from '@ar.io/wayfinder-core'

const response = await wayfinder.request('ar://transaction-id', {
  verificationSettings: {
    enabled: true,
    strategy: new HashVerificationStrategy({
      trustedGateways: [new URL('https://arweave.net')],
    }),
    strict: true,
    events: {
      onVerificationSucceeded: (event) => {
        console.log('Verification passed for:', event.txId)
      },
      onVerificationFailed: (error) => {
        console.error('Verification failed:', error)
      },
    },
  },
})

Override Routing Settings

import { FastestPingRoutingStrategy } from '@ar.io/wayfinder-core'

const response = await wayfinder.request('ar://transaction-id', {
  routingSettings: {
    strategy: new FastestPingRoutingStrategy({ timeoutMs: 500 }),
    events: {
      onRoutingSucceeded: (event) => {
        console.log('Selected gateway:', event.selectedGateway)
      },
    },
  },
})

Supported URL Formats

Transaction IDs

await wayfinder.request('ar://ABC123...XYZ')

ArNS Names

await wayfinder.request('ar://domain-name')
await wayfinder.request('ar://domain-name/path/to/file.txt')
await wayfinder.request('ar://subdomain.domain-name')

Gateway Endpoints

await wayfinder.request('ar:///info') // Gateway information
await wayfinder.request('ar:///peers') // Network peers (if supported)
await wayfinder.request('ar:///graphql') // GraphQL endpoint (if supported)

Gateway endpoint availability varies by gateway implementation. The /info endpoint is standard, while others like /peers and /graphql may not be available on all gateways.

Additional Usage Patterns

For advanced usage patterns, configuration options, and detailed examples, refer to the MDN Fetch API documentation. Since wayfinder.request() is a wrapper around the native fetch function, all standard fetch patterns apply:

  • Request configuration and headers
  • Response processing methods
  • Streaming data handling
  • Caching strategies
  • CORS handling
  • Error types and handling

The Wayfinder-specific additions (verification and routing overrides) work seamlessly with all standard fetch functionality.

Was this page helpful?