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 inputinit
(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',
})
Related
- resolveUrl(): Resolve ar:// URLs without fetching data
- Gateway Providers: Understand gateway discovery options
- Routing Strategies: Explore different routing algorithms
- Verification Strategies: Learn about data integrity verification
- Telemetry: Set up monitoring and observability