# x402labs.sh documentation

## Overview

Canonical URL: https://x402labs.sh/docs/overview

Understand how x402labs exposes useful, account-free services to agents and developers.

## What is x402labs?

x402labs is a collection of focused HTTP services designed for software agents. Each service uses
ordinary HTTP, publishes its contract through OpenAPI, and charges a small fixed amount per call
through the x402 protocol.

There are no accounts, API keys, usage tiers, or monthly subscriptions. A compatible client asks
for a resource, receives an HTTP `402 Payment Required` challenge, signs the requested payment, and
retries the same request with proof attached.

## Available services

The service catalog currently covers web extraction and public Truth Social data:

- `POST /v1/scraping/scrape` extracts content from public web pages through Firecrawl.
- `GET /v1/social/truthsocial/profile` returns a public profile.
- `GET /v1/social/truthsocial/user-posts` returns a profile's posts.
- `GET /v1/social/truthsocial/post` returns one public post by URL.
- `GET /v1/pricing` lists currently available paid routes and exact prices.

The [live API reference](/reference) is generated from `/openapi.json`; treat it as the source of
truth for request and response fields.

## Service architecture

Every route passes through the same service shell: payment verification, payment replay protection,
rate limiting, structured logs, and metrics. Service plugins focus on their upstream integration
instead of reimplementing infrastructure.

## Choose an integration

- Use HTTP directly when your runtime already supports x402.
- Use the public OpenAPI document for generated clients, validation, or discovery.

---

## Quick start

Canonical URL: https://x402labs.sh/docs/quick-start

Discover pricing and make your first x402-protected scraping request.

## 1. Inspect the public contract

No authentication is needed to inspect the service:

```bash
curl https://test.x402labs.sh/v1/pricing
curl https://test.x402labs.sh/openapi.json
```

Pricing is dynamic. Read `/v1/pricing` before enforcing a maximum payment in your client.

## 2. Send the request

An unsigned request demonstrates the normal HTTP negotiation:

```bash
curl -i https://test.x402labs.sh/v1/scraping/scrape \
  -H 'content-type: application/json' \
  --data '{"url":"https://example.com","formats":["markdown"],"onlyMainContent":true}'
```

When payments are enabled, the API answers with `402 Payment Required` and a machine-readable
payment challenge. A compatible x402 client signs that challenge and repeats the request.

## 3. Use an x402 client

Configure your wallet in the client runtime, never in browser code or committed configuration. The
client performs the challenge, payment, and retry sequence while your application handles the final
JSON response.

```ts
const response = await paidFetch('https://test.x402labs.sh/v1/scraping/scrape', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    url: 'https://example.com',
    formats: ['markdown'],
    onlyMainContent: true,
  }),
});

const result = await response.json();
```

The exact wrapper API depends on your x402 client version. Consult that client's documentation for
wallet construction and network support.

## Next steps

Read [x402 payments](/docs/payments) for the protocol flow or [scraping](/docs/scraping) to choose
the right endpoint.

---

## x402 payments

Canonical URL: https://x402labs.sh/docs/payments

Learn the challenge, signing, settlement, and safe retry flow used by paid routes.

## The payment flow

The API uses the HTTP `402 Payment Required` status as a negotiation mechanism:

1. Your client sends the intended request without payment proof.
2. The server returns acceptable payment requirements, including asset, amount, network, and payee.
3. The client checks the requirement against its policy and signs a payment authorization.
4. It retries the same request with the payment payload.
5. The server verifies and settles the payment before returning the resource.

## Set a maximum payment

Treat payment requirements as untrusted input. A production client should compare the challenge
against `/v1/pricing`, enforce a hard maximum amount, allow only expected networks and assets, and
verify the payee.

## Safe retries

Network failures can occur after a payment is accepted but before the response reaches your client.
x402labs supports payment identifiers so a compatible retry can replay the cached response
instead of charging twice.

Preserve your client's payment identifier across a retry. Do not create a new payment authorization
until you know the original attempt cannot be recovered.

## Keep keys out of the browser

This documentation site never asks for or stores wallet secrets. Run paid calls from a trusted agent,
backend, CLI, or wallet-aware runtime. A browser playground is intentionally not included.

## Public metadata

- `/v1/pricing` exposes current route prices and networks.
- `/openapi.json` exposes request and response contracts.
- x402 Bazaar metadata lets compatible discovery systems index paid resources.

---

## Scraping API

Canonical URL: https://x402labs.sh/docs/scraping

Convert public web pages into clean HTML or Markdown with Firecrawl.

## Scrape a page

Use `POST /v1/scraping/scrape` to extract a public page. The route supports browser rendering,
waiting, clicking, custom headers, PDF parsing, and other Firecrawl capabilities.

```json
{
  "url": "https://example.com",
  "formats": ["markdown"],
  "onlyMainContent": true,
  "waitFor": 1000,
  "blockAds": true
}
```

The Firecrawl route supports advanced options such as include and exclude tags, mobile rendering,
actions, parser selection, location preferences, cache behavior, and zero-data-retention requests.
See the [generated API reference](/reference) for the current field contract.

## URL safety policy

The route evaluates target URLs before fetching. Private networks, local addresses, unsupported
protocols, and configured blocked domains are rejected.

## Output

Responses follow the upstream Firecrawl service shape. Success schemas are deliberately shown as
flexible in OpenAPI until the backend publishes stricter response contracts.

---

## Truth Social API

Canonical URL: https://x402labs.sh/docs/social

Fetch public Truth Social profiles, user timelines, and individual posts.

## Available endpoints

The social service exposes public Truth Social data through ScrapeCreators. Every route is protected
by x402 and returns the upstream JSON response without inventing a second response format.

- `GET /v1/social/truthsocial/profile` looks up a profile by handle.
- `GET /v1/social/truthsocial/user-posts` returns a user's posts with pagination support.
- `GET /v1/social/truthsocial/post` fetches one post from its canonical Truth Social URL.

Use the [generated API reference](/reference) for current prices, query parameters, and response
statuses.

## Fetch a profile

Pass the username without an `@` prefix:

```text
GET /v1/social/truthsocial/profile?handle=realDonaldTrump
```

The service normalizes handles for caching. Profile results are cached briefly to reduce upstream
latency without keeping stale profile data for long periods.

## Fetch user posts

Identify the account with either `handle` or `userId`. At least one is required.

```text
GET /v1/social/truthsocial/user-posts?handle=realDonaldTrump&trim=true
```

Set `trim=true` for a smaller response when the upstream supports it. To request the next page, pass
the returned pagination cursor as `nextMaxId`:

```text
GET /v1/social/truthsocial/user-posts?userId=107780257626128497&nextMaxId=114315219437063159
```

First-page timelines use a short cache lifetime. Paginated historical results are cached longer
because they change less frequently.

## Fetch one post

Pass the complete public post URL as an encoded `url` query parameter:

```text
GET /v1/social/truthsocial/post?url=https%3A%2F%2Ftruthsocial.com%2F%40realDonaldTrump%2Fposts%2F114315219437063160
```

URL fragments are removed before cache lookup. Invalid URLs fail validation before an upstream
request is made.

## Errors and retries

Validation failures return `400`. Upstream authentication, policy, missing-resource, rate-limit, and
availability errors may return `401`, `403`, `404`, `429`, or `503`. Retry only transient `429` and
`503` responses, preserve the payment identifier, and use exponential backoff.

The service degrades gracefully when its cache is unavailable: requests continue to the upstream
provider and cache failures are recorded in structured logs.

---

## Errors and limits

Canonical URL: https://x402labs.sh/docs/errors

Handle validation, payment, policy, upstream, and rate-limit failures predictably.

## Error envelope

Service errors use a compact JSON envelope:

```json
{
  "error": {
    "message": "Human-readable summary",
    "code": "MACHINE_READABLE_CODE",
    "details": {}
  }
}
```

Do not parse the message. Branch on the HTTP status and stable `code` when present.

## Common statuses

- `400` — request validation failed. Correct the payload before retrying.
- `402` — payment is required or payment verification failed. Follow the x402 challenge.
- `403` — the target URL is blocked by policy. Do not retry the same URL.
- `413` — the upstream response exceeds the configured limit.
- `429` — the route's rate limit was exceeded. Respect retry headers and back off.
- `502` — a direct upstream fetch failed.
- `503` — a required upstream integration is unavailable or not configured.

## Retry policy

Retry transient `429`, `502`, and `503` responses with exponential backoff and jitter. Cap attempts,
preserve payment identifiers, and avoid retrying validation or policy failures.

## Rate-limit identity

Paid traffic is limited by payment or wallet identity rather than relying only on source IP.
Individual routes can publish different limits. Limits protect upstream capacity and do not replace
your own concurrency controls.

## Observability

Responses include request correlation metadata where available. Preserve it in logs when reporting a
failure, but never log wallet private keys or full payment payloads.