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

> ## Agent Instructions
> Xintel agents pay for shared report bodies only via x402 — never profile, posts, or edges.
> Preferred flow: GET /api/intel/list → GET /api/intel/reports?username= (menu) → select=all|range with X-402-Payment.
> Docs: https://docs.xintel.aispace.bot — App: https://xintel.aispace.bot — Agent playbook: /agents.md

# Quickstart

> Call the Xintel Agent API — free shelf and menu, then pay x402 for report bodies.

# Agent API quickstart

**Audience:** developers and agents integrating over HTTP.\
**Prerequisites:** a Base USDC wallet (production facilitator), or local `X402_AGENT_TEST_MODE` for signature-only smoke tests.\
**Base URL:** `https://xintel.aispace.bot` (or `http://localhost:5173` when developing).

## Flow

```text theme={null}
1. GET /api/intel/list                          → free shelf
2. GET /api/intel/reports?username=AskVenice    → free menu (ids, dates)
3. GET …&select=all   (or select=range&…)       → 402 Payment required
4. Retry with X-402-Payment (settled)           → IntelReportSnapshot[]
```

## 1. Free shelf

```bash theme={null}
curl -sS "https://xintel.aispace.bot/api/intel/list"
```

Example shape:

```json theme={null}
{
  "configured": true,
  "entries": [
    {
      "username": "AskVenice",
      "displayName": "…",
      "reportCount": 3,
      "postCount": 40,
      "gatheredAt": "2026-07-20T12:00:00.000Z"
    }
  ]
}
```

Index rows also include avatar and follower fields; use `username` and `reportCount` to pick a handle.

## 2. Free report menu

```bash theme={null}
curl -sS "https://xintel.aispace.bot/api/intel/reports?username=AskVenice"
```

```json theme={null}
{
  "username": "AskVenice",
  "reportCount": 2,
  "reports": [
    {
      "id": "rpt_…",
      "createdAt": "2026-07-20T12:00:00.000Z",
      "model": "…",
      "postCount": 40,
      "dateRange": { "from": "…", "to": "…" }
    }
  ]
}
```

Metadata only — no narrative or analytics bodies yet.

## 3. Request bodies (expect 402)

```bash theme={null}
curl -sS -i \
  "https://xintel.aispace.bot/api/intel/reports?username=AskVenice&select=all"
```

Without payment you get **402** and an x402 v2 challenge (`accepts`, `extensions` with `unitPriceUsd`, `reportCount`, etc.).

## 4. Pay and retry

Settle the challenge (production: x402 facilitator / EIP-3009 TransferWithAuthorization on Base USDC), then retry the same URL with:

```http theme={null}
X-402-Payment: <payment-payload>
```

(`X-Payment` is also accepted.)

```bash theme={null}
curl -sS \
  -H "X-402-Payment: $PAYMENT" \
  "https://xintel.aispace.bot/api/intel/reports?username=AskVenice&select=all"
```

Success returns `{ username, select, reportCount, chargedUsd, reports: IntelReportSnapshot[] }`.

## Range example

```bash theme={null}
# By ids
curl -sS -i \
  "https://xintel.aispace.bot/api/intel/reports?username=AskVenice&select=range&ids=rpt_a,rpt_b"

# By createdAt window (ISO strings; inclusive string compare)
curl -sS -i \
  "https://xintel.aispace.bot/api/intel/reports?username=AskVenice&select=range&from=2026-01-01T00:00:00.000Z&to=2026-12-31T23:59:59.999Z"
```

Price = **\$0.01 × N** matching reports (override via `X402_INTEL_REPORT_USD` on the deployment).

## Next

* [Auth and payment](/agent-api/auth-and-payment)
* [Reports](/agent-api/reports)
* [Agent playbook](/agents)