> ## Documentation Index
> Fetch the complete documentation index at: https://docs.faremeter.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Rides SDK

> The high-level SDK for making x402 payments with zero configuration.

`@faremeter/rides` is the simplest way to use faremeter. It bundles all payment handlers and wallet adapters into a single package with automatic wallet detection.

```bash theme={null}
pnpm add @faremeter/rides
```

## Basic usage

```typescript theme={null}
import { payer } from "@faremeter/rides"

await payer.addLocalWallet(process.env.PAYER_KEYPAIR_PATH)
const response = await payer.fetch("https://api.example.com/resource")
```

## The `payer` singleton

`payer` is a pre-configured singleton with sensible defaults. It supports all chains and assets out of the box.

### `addLocalWallet`

```typescript theme={null}
await payer.addLocalWallet(input: unknown): Promise<void>
```

Adds a wallet to the payer. Auto-detects the wallet type:

* **File path** (e.g., `~/.config/solana/id.json`) -- Treated as a Solana keypair file.
* **JSON array** (e.g., `[123, 45, ...]`) -- Treated as Solana keypair bytes.
* **Base64 string** -- Treated as a Solana keypair.
* **Hex string starting with `0x`** -- Treated as an EVM private key.

Multiple wallets can be added. The payer will use the first wallet that matches a payment requirement.

### `addWalletAdapter`

```typescript theme={null}
payer.addWalletAdapter(adapter: WalletAdapter): void
```

Registers a wallet adapter directly. Use this for wallet types that `addLocalWallet` cannot auto-detect, such as OWS, Ledger, or Crossmint wallets.

A `WalletAdapter` has three fields:

| Field            | Type                     | Description                                                    |
| ---------------- | ------------------------ | -------------------------------------------------------------- |
| `x402Id`         | `PaymentIdV2[]`          | Payment schemes this wallet supports (scheme, network, asset). |
| `paymentHandler` | `PaymentHandler`         | The payment handler that uses this wallet for signing.         |
| `getBalance`     | `() => Promise<Balance>` | Returns the wallet's current balance for pre-payment checks.   |

Example with an OWS Solana wallet:

```typescript theme={null}
import { createPayer, type WalletAdapter } from "@faremeter/rides"
import { createOWSSolanaWallet } from "@faremeter/wallet-ows"
import { createPaymentHandler } from "@faremeter/payment-solana/exact"
import { lookupKnownSPLToken, clusterToCAIP2 } from "@faremeter/info/solana"
import { getTokenBalance } from "@faremeter/payment-solana/splToken"
import { Connection, PublicKey, clusterApiUrl } from "@solana/web3.js"
import { createSolanaRpc } from "@solana/kit"

const network = "devnet"
const usdcInfo = lookupKnownSPLToken(network, "USDC")
if (!usdcInfo) throw new Error("Unknown SPL token")

const wallet = createOWSSolanaWallet(network, {
  walletNameOrId: "my-solana-wallet",
  passphrase: "my-passphrase",
})

const mint = new PublicKey(usdcInfo.address)
const connection = new Connection(clusterApiUrl(network), "confirmed")
const rpcClient = createSolanaRpc(clusterApiUrl(network))

const adapter: WalletAdapter = {
  x402Id: [{
    scheme: "exact",
    network: clusterToCAIP2(network).caip2,
    asset: usdcInfo.address,
  }],
  paymentHandler: createPaymentHandler(wallet, mint, connection),
  getBalance: async () => {
    const balance = await getTokenBalance({
      account: wallet.publicKey.toBase58(),
      asset: usdcInfo.address,
      rpcClient,
    })
    return { name: "USDC", amount: balance?.amount ?? 0n, decimals: balance?.decimals ?? 6 }
  },
}

const payer = createPayer()
payer.addWalletAdapter(adapter)

const response = await payer.fetch("https://api.example.com/resource")
```

### `fetch`

```typescript theme={null}
await payer.fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>
```

Drop-in replacement for the global `fetch`. If the server responds with 402, rides handles payment negotiation and retries the request automatically.

## `createPayer`

For more control, create a custom payer instance:

```typescript theme={null}
import { createPayer } from "@faremeter/rides"

const customPayer = createPayer({
  networks: ["solana-devnet", "base-sepolia"],
  assets: ["USDC"],
  options: {
    disableBalanceChecks: true,
  },
})

await customPayer.addLocalWallet(process.env.PAYER_KEYPAIR_PATH)
const response = await customPayer.fetch("https://api.example.com/resource")
```

### Options

| Option                         | Type             | Default       | Description                                            |
| ------------------------------ | ---------------- | ------------- | ------------------------------------------------------ |
| `networks`                     | `KnownNetwork[]` | All supported | Restrict to specific networks.                         |
| `assets`                       | `KnownAsset[]`   | All supported | Restrict to specific assets.                           |
| `options.disableBalanceChecks` | `boolean`        | `false`       | Skip balance checks before payment.                    |
| `options.fetch`                | `WrapOpts`       | --            | Pass-through options for the underlying fetch wrapper. |

## Multi-chain support

Add wallets for different chains. Rides selects the correct one based on the server's payment requirements.

```typescript theme={null}
import { payer } from "@faremeter/rides"

await payer.addLocalWallet(process.env.PAYER_KEYPAIR_PATH)
await payer.addLocalWallet(process.env.EVM_PRIVATE_KEY)

const response = await payer.fetch("https://api.example.com/resource")
```

## When to use rides vs fetch

Use rides when:

* You want the fastest setup with minimal configuration.
* You do not need custom payer selection logic.
* You are building a simple agent or script.

Use `@faremeter/fetch` when:

* You need custom payment handlers or payer choosers.
* You want to control which handlers are registered.
* You need separate fetch instances with different configurations.

See [Fetch Wrapper](/client/fetch-wrapper) for the lower-level approach.