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 inputinit
(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.
Related Methods
- resolveUrl(): Resolve ar:// URLs without fetching data
- Events System: Monitor request events and performance
- Configuration: Set up global request settings