Integration Guide

AI Agent x402 Integration

Learn how to interact with the LuxeOracle API using the HTTP 402 Payment Required protocol to retrieve real-time luxury inventory data.

The x402 Flow

LuxeOracle uses the Request → Challenge → Sign → Delivery micro-payment standard designed for machine-to-machine interactions. Each query consumes 0.005 USDC on the Base network. You pay zero gas fees.

1 Initial Request: Get the payment challenge automatically.
2 Off-Chain Signature: Your Agent signs an authorization off-chain (gasless).
3 Verify & Dispatch: The server verifies the signature, settles the payment, and triggers the scraper.

Step 1. Configure x402 Client

Set up the x402 client with your AI Agent's private key. The client will only be used to sign off-chain authorizations, meaning you pay zero gas.

Node.js Setup

import { wrapFetchWithPayment, x402Client } from '@x402/fetch';
import { ExactEvmScheme } from '@x402/evm/exact/client';
import { privateKeyToAccount } from 'viem/accounts';

const account = privateKeyToAccount("AGENT_PRIVATE_KEY");

// Create x402 client with EVM exact scheme
const client = new x402Client();
client.register('eip155:*', new ExactEvmScheme(account));

// Wrap native fetch
const fetchWithPayment = wrapFetchWithPayment(fetch, client);

Step 2. Make the Request

Simply use the wrapped fetch. It will automatically handle the 402 challenge, create an off-chain signature, and retry the request. The server's facilitator will pay the gas for you.

Node.js Example

// Make request to the protected endpoint
const response = await fetchWithPayment(
  'http://api.luxeoracle.com/v1/monitor/tw/hermes/picotin'
);

// Check if payment was accepted
if (response.status === 202) {
  const data = await response.json();
  console.log("Job ID:", data.jobId);
}

Note: Booting up the headless browser and bypassing anti-bot mechanisms takes a few seconds. Agents should use the jobId to poll for the result after the retry_after delay, or wait for an incoming Webhook.