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

# Quickstart

> Make your first payment-gated API request

# Quickstart Guide

Get started with HTTPayer in under 5 minutes.

## Proxy Endpoint

### Prerequisites

* A HTTPayer API key (contact the team to get one)

### Step 1: Get Your API Key and Set Up Your Environment

Contact the HTTPayer team to receive your API key. You'll use this in the `X-API-KEY` header for all requests.

### Step 2: Make a Simulation Request

Test the payment flow without executing a transaction.

Typescript:

```Typescript theme={null}
const HTTPAYER_API_KEY = process.env.HTTPAYER_API_KEY;

if (!HTTPAYER_API_KEY) {
  throw new Error("HTTPAYER_API_KEY is not set");
}

const TARGET_API = "https://api.itsgloria.ai/news?feed_categories=ai,crypto";

const payload = {
  api_url: TARGET_API,
  method: "GET",
};

const response = await fetch("https://api.httpayer.com/proxy/sim", {
  method: "POST",
  headers: {
    Accept: "application/json",
    "Content-Type": "application/json",
    "X-API-KEY": HTTPAYER_API_KEY
  },
  body: JSON.stringify(payload),
});

const data = await response.json();

console.log(JSON.stringify(data, null, 2));
```

Python:

```Python theme={null}
import requests
import json

TARGET_API = "https://api.itsgloria.ai/news?feed_categories=ai,crypto"

session = requests.Session()

payload = {
  "api_url": TARGET_API,
  "method": "GET",
}
headers = {"X-API-KEY": HTTPAYER_API_KEY, "Content-Type": "application/json"}

response = session.post("https://api.httpayer.com/proxy/sim", headers=headers, json=payload)
print(json.dumps(response.json(), indent=2))
```

**Response:**

```json theme={null}
{
  "dryRun": true,
  "paymentInstructions": {
    "scheme": "exact",
    "network": "base",
    "maxAmountRequired": "30000",
    "resource": "https://api.itsgloria.ai/news",
    "description": "Get the latest news about a covered news topic, delivering the most recent 10 headlines.",
    "mimeType": "application/json",
    "payTo": "0xCa1271E777C209e171826A681855351f4989cd0c",
    "maxTimeoutSeconds": 60,
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
  }
}
```

### Step 3: Make a Payment-Gated Request

Execute the full payment + request flow using the `/proxy` endpoint.

Typescript:

```Typescript theme={null}
const HTTPAYER_API_KEY = process.env.HTTPAYER_API_KEY;

if (!HTTPAYER_API_KEY) {
  throw new Error("HTTPAYER_API_KEY is not set");
}

const TARGET_API = "https://api.itsgloria.ai/news?feed_categories=ai,crypto";

const payload = {
  api_url: TARGET_API,
  method: "GET",
};

const response = await fetch("https://api.httpayer.com/proxy", {
  method: "POST",
  headers: {
    Accept: "application/json",
    "Content-Type": "application/json",
    "X-API-KEY": HTTPAYER_API_KEY
  },
  body: JSON.stringify(payload),
});

const data = await response.json();
const respBody = data.body;

console.log(JSON.stringify(respBody, null, 2));
```

Python:

```Python theme={null}
import requests
import json

HTTPAYER_API_KEY = os.getenv("HTTPAYER_API_KEY")

TARGET_API = "https://api.itsgloria.ai/news?feed_categories=ai,crypto"

session = requests.Session()

payload = {
  "api_url": TARGET_API,
  "method": "GET",
}
headers = {"X-API-KEY": HTTPAYER_API_KEY, "Content-Type": "application/json"}

response = session.post("https://api.httpayer.com/proxy", headers=headers, json=payload)
print(json.dumps(response.json(), indent=2))
```

## Relay Endpoint

### Prerequisites

* USDC on Base, Base Sepolia, SKALE Base, SKALE Base Sepolia, Solana, or Solana Devnet
* A HTTP client configured with x402 payment abilities (x402-fetch on Typescript, x402 on Python)

### Step 1: Create a Wallet Client

Typescript:

```Typescript theme={null}
import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { wrapFetchWithPayment } from "x402-fetch";
import { baseSepolia } from "viem/chains";

// Create a wallet client
const account = privateKeyToAccount("0xYourPrivateKey");
const client = createWalletClient({
  account,
  transport: http(),
  chain: baseSepolia,
});

// Wrap the fetch function with payment handling
const fetchWithPay = wrapFetchWithPayment(fetch, client);
```

Python:

```Python theme={null}
import json
from eth_account import Account
from x402.clients.requests import x402_requests

# Initialize account
account = Account.from_key("your_private_key")

# Create session and make request
session = x402_requests(account)
```

### Step 2: Make a Simulation Request

Test the payment flow without executing a transaction.

Typescript:

```Typescript theme={null}
const TARGET_API = "https://api.itsgloria.ai/news?feed_categories=ai,crypto";

const payload = {
  api_url: TARGET_API,
  method: "GET",
  network: "base"
}

const response = await fetchWithPay("https://api.httpayer.com/relay/sim", {
  method: "POST",
  headers: {
    Accept: "application/json",
    "Content-Type": "application/json",
  },
  body: JSON.stringify(payload),
});

const data = await response.json();

console.log(JSON.stringify(data, null, 2));
```

Python:

```Python theme={null}
TARGET_API = "https://api.itsgloria.ai/news?feed_categories=ai,crypto"

payload = {
  "api_url": TARGET_API,
  "method": "GET",
  "network": "base"
}
headers = {"Content-Type": "application/json"}

response = session.post("https://api.httpayer.com/relay/sim", headers=headers, json=payload)
print(json.dumps(response.json(), indent=2))
```

**Response:**

```json theme={null}
{
  "requiresPayment": true,
  "targetPaymentRequirements": {
    "scheme": "exact",
    "network": "base",
    "maxAmountRequired": "30000",
    "resource": "https://api.itsgloria.ai/news",
    "description": "Get the latest news about
a covered news topic, delivering the most recent 10 headlines.",
    "mimeType": "application/json",
    "payTo": "0xCa1271E777C209e171826A681855351f4989cd0c",
    "maxTimeoutSeconds": 60,
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
  }
}
```

### Step 3: Make a Payment-Gated Request

Execute the full payment + request flow using the `/relay` endpoint.

Typescript:

```Typescript theme={null}
const TARGET_API = "https://api.itsgloria.ai/news?feed_categories=ai,crypto";

const payload = {
  api_url: TARGET_API,
  method: "GET",
  network: "base"
}

const response = await fetchWithPay("https://api.httpayer.com/relay", {
  method: "POST",
  headers: {
    Accept: "application/json",
    "Content-Type": "application/json",
  },
  body: JSON.stringify(payload),
});

const data = await response.json();
const respBody = data.body;

console.log(JSON.stringify(respBody, null, 2));
```

Python:

```Python theme={null}
TARGET_API = "https://api.itsgloria.ai/news?feed_categories=ai,crypto"

payload = {
  "api_url": TARGET_API,
  "method": "GET",
  "network": "base"
}
headers = {"Content-Type": "application/json"}

response = session.post("https://api.httpayer.com/relay", headers=headers, json=payload)
print(json.dumps(response.json(), indent=2))
```

## Forwarding Request Data

Both `/proxy` and `/relay` support forwarding arbitrary request data to the target API. The following fields can be included alongside `api_url` and `method`:

| Field     | Type             | Description                                                                                                       |
| --------- | ---------------- | ----------------------------------------------------------------------------------------------------------------- |
| `json`    | object           | JSON body — serialized with `Content-Type: application/json`. Mirrors `requests(json=...)`.                       |
| `body`    | object \| string | Alias for `json`. Interchangeable when passing a dict or pre-serialized string.                                   |
| `data`    | object \| string | Form-encoded body (object) or raw string body. Mirrors `requests(data=...)`.                                      |
| `params`  | object           | Query parameters appended to `api_url`.                                                                           |
| `headers` | object           | Custom headers forwarded to the target API.                                                                       |
| `auth`    | object           | Basic auth shorthand — `{ "username": "...", "password": "..." }`. Converted to an `Authorization: Basic` header. |
| `cookies` | object           | Cookie shorthand — `{ "session": "abc" }`. Merged into the `Cookie` header.                                       |

Example POST with JSON body and custom headers:

```json theme={null}
{
  "api_url": "https://api.example.com/process",
  "method": "POST",
  "json": { "input": "hello" },
  "headers": { "X-Request-ID": "abc123" }
}
```

Example POST with Basic auth:

```json theme={null}
{
  "api_url": "https://api.example.com/data",
  "method": "GET",
  "auth": { "username": "myuser", "password": "mypass" }
}
```

***

## Next Steps

<CardGroup cols={2}>
  <Card title="API Reference" icon="book" href="/api/introduction">
    Explore all available endpoints
  </Card>

  <Card title="Payment Relay" icon="arrows-repeat" href="/api/relay/execute-cross-chain-relay-payment">
    Learn about the relay endpoint
  </Card>

  <Card title="Check Balance" icon="wallet" href="/api/account/get-account-balance">
    View your account balance
  </Card>
</CardGroup>

## Support

Need help? Reach out to the HTTPayer team or check out our [GitHub repository](https://github.com/httpayer).