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

# Quickstart: Make Your First x402 Paid API Call Now

> Call a live x402-protected route with automatic USDC micropayment in under five minutes using test USDC on the Meterlane sandbox on Base Sepolia.

This guide walks you through calling a live x402-protected route on the Meterlane public sandbox. Your agent client will receive an **HTTP 402**, sign a USDC payment, and automatically retry — getting back **HTTP 200** with the response body. The whole flow runs on Base Sepolia with test USDC, so no real funds are involved.

<Steps>
  <Step title="Sign up and create an org">
    Go to [meterlane.app](https://meterlane.app) and sign up. During onboarding you will create your first **org** — this is your tenant namespace in Meterlane. Your org holds API keys, routes, and wallet settings.

    You do not need a production plan to follow this guide. The sandbox is available immediately after signup.
  </Step>

  <Step title="Get a Base Sepolia wallet with test USDC">
    You need an EVM wallet private key and some test USDC on Base Sepolia (`eip155:84532`).

    1. Generate a new wallet (use [Coinbase Wallet](https://wallet.coinbase.com), MetaMask, or any EVM wallet that exports a raw private key).
    2. Visit the [Circle Faucet](https://faucet.circle.com), select **Base Sepolia**, and request test USDC for your wallet address.
    3. Store the private key in an environment variable — never commit it to source control.

    ```bash theme={null}
    export AGENT_PRIVATE_KEY=0xYOUR_PRIVATE_KEY_HERE
    ```

    <Warning>
      Use a **dedicated hot wallet** with only test USDC. Never reuse a cold-storage key or a key holding real funds.
    </Warning>
  </Step>

  <Step title="Install the SDK">
    Install the `@meterlane/x402` package. The `client` subpath is MIT-licensed and open source.

    <Tabs>
      <Tab title="npm">
        ```bash theme={null}
        npm install @meterlane/x402
        ```
      </Tab>

      <Tab title="pnpm">
        ```bash theme={null}
        pnpm add @meterlane/x402
        ```
      </Tab>

      <Tab title="yarn">
        ```bash theme={null}
        yarn add @meterlane/x402
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Make a paid request">
    The public demo route at `https://gateway.meterlane.app/gateway/demo/demo` is a live x402-protected endpoint on Base Sepolia. Use `createAgentClient` to wrap `fetch` with automatic payment handling.

    ```typescript theme={null}
    import type { Hex } from "viem";
    import { createAgentClient } from "@meterlane/x402/client";

    const privateKey = process.env.AGENT_PRIVATE_KEY as Hex;

    // Defaults to Base Sepolia (eip155:84532) — safe for sandbox
    const paidFetch = createAgentClient(privateKey);

    const res = await paidFetch(
      "https://gateway.meterlane.app/gateway/demo/demo",
      { method: "GET" }
    );

    console.log(res.status);          // 200
    console.log(await res.text());    // Response body from the demo route
    ```

    `createAgentClient` accepts an optional second argument to pin the network:

    ```typescript theme={null}
    // Explicit Base Sepolia — same as the default
    const paidFetch = createAgentClient(privateKey, "eip155:84532");
    ```

    <Note>
      Base mainnet (`eip155:8453`) requires a private mainnet-capable facilitator. The public sandbox facilitator only supports Base Sepolia. Contact the Meterlane team when you are ready for production.
    </Note>
  </Step>

  <Step title="Understand the 402 → payment → 200 flow">
    Here is exactly what happens under the hood when you call `paidFetch`:

    1. **First request** — your client sends a plain `GET`. The gateway has no payment yet, so it returns **HTTP 402 Payment Required** with an `X-Payment-Requirements` header describing the USDC price, network, and facilitator address.
    2. **Payment signing** — `createAgentClient` reads the requirements, constructs an ERC-3009 `transferWithAuthorization` signed by your private key, and encodes it as the `X-PAYMENT` header value.
    3. **Retry with payment** — the client retries the same request, this time including `X-PAYMENT`.
    4. **Verification and proxy** — the gateway submits the signed authorization to the x402 facilitator, which settles the USDC transfer on-chain. The gateway then proxies the request to the upstream route and returns **HTTP 200**.

    You can probe the route without a wallet to see the raw 402:

    ```bash theme={null}
    curl -i https://gateway.meterlane.app/gateway/demo/demo
    ```

    The response will look like this:

    ```http theme={null}
    HTTP/2 402
    x-payment-requirements: {"scheme":"exact","network":"eip155:84532","maxAmountRequired":"1000000","resource":"...","description":"...","mimeType":"application/json","payTo":"0x...","maxTimeoutSeconds":60,"asset":"0x...","extra":{"name":"USDC","decimals":6}}
    content-type: application/json

    {"error":"Payment required"}
    ```
  </Step>
</Steps>

## What to do next

Now that you have seen the full payment flow, you can create your own protected routes from the dashboard and point agents at your org's gateway URL.

<CardGroup cols={2}>
  <Card title="Agent Gateway Overview" icon="server" href="/gateway/overview">
    Create routes, set per-request prices, and manage API keys for your org.
  </Card>

  <Card title="Key Concepts" icon="book" href="/concepts">
    Understand x402, facilitators, ERC-3009, and how Meterlane routes work.
  </Card>

  <Card title="Stablecoin Corridor" icon="arrow-right-arrow-left" href="/corridor/overview">
    Send USDC to local fiat beneficiaries in BRL, MXN, NGN, KES, or ZAR.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference">
    Full REST reference for gateway and corridor endpoints.
  </Card>
</CardGroup>