Skip to main content

Setup

Set up your payment handler in just 3 lines:
import { payer } from "@faremeter/rides";

const { PAYER_KEYPAIR } = process.env;
if (!PAYER_KEYPAIR) throw new Error("PAYER_KEYPAIR must be set");

await payer.addLocalWallet(PAYER_KEYPAIR);
@faremeter/rides automatically detects your network, looks up USDC, and sets up payments using your existing wallet. All examples below use payer.fetch().

Example: Create Crawl Job

Create a new web crawl job with JavaScript rendering and screenshot capture:
const url = "https://uprock.api.corbits.dev/crawl/v1/new";

const requestBody = {
  url: "https://example.com",
  method: "CRAWL_FULL_PAGE",
  timeout_sec: 120,
  placement: {
    and: [
      { capability: "CAPTURE_DOM" },
      { capability: "RENDER_JAVASCRIPT" },
      { capability: "TAKE_SCREENSHOT" },
      {
        or: [
          { code: "US" },
          { code: "CA" },
          { code: "MX" }
        ]
      }
    ]
  }
};

const response = await payer.fetch(url, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify(requestBody),
});

if (!response.ok) {
  const text = await response.text().catch(() => "");
  throw new Error(`HTTP ${response.status} ${response.statusText} ${text}`);
}

const data = await response.json();
console.log("Crawl result:", data);

Request Parameters

ParameterTypeDescription
urlstringThe URL to crawl
methodstringCrawl method (e.g., CRAWL_FULL_PAGE)
timeout_secnumberRequest timeout in seconds
placementobjectPlacement rules for node selection

Placement Capabilities

CapabilityDescription
CAPTURE_DOMCapture the page’s DOM structure
RENDER_JAVASCRIPTExecute JavaScript before capturing
TAKE_SCREENSHOTGenerate a screenshot of the page

Geo-targeting

Use country codes in the placement.or array to target specific regions:
  • US - United States
  • CA - Canada
  • MX - Mexico

Payment Flow

When you make a request, the following happens automatically:
  1. Initial Request: Client sends crawl request
  2. 402 Response: Proxy returns payment requirements
{
  "accepts": [{
    "network": "solana-mainnet-beta",
    "maxAmountRequired": 10000,
    "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "payTo": "HYi3Uu5n6yYmpTAHfk8WVdwjhMHeV5rRGTYviePF1xTy"
  }]
}
  1. Payment: Payment handler processes USDC transfer (0.01 USDC)
  2. Success: Proxy fulfills original request with 200 OK
All of this is handled automatically by payer.fetch() or fetchWithPayer!

External Resources