Overview

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

Parameters

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

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

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

const wayfinder = new Wayfinder({
  gatewaysProvider: new NetworkGatewaysProvider({
    ario: ARIO.mainnet()
  }),
})

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

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

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

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)

overrides

For a given request, you can override the initialized routing and verification settings by passing an overrides option to wayfinder.request(). This allows you to specify a different routing strategy, verification strategy, or even a custom logger for just that request, without affecting the global configuration.

Example:

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)
      },
    },
  },
})

Advanced Configurations

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',
})

Was this page helpful?