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

# Deep Research API

> Paid web-research pipeline: multi-source scan with cited sources, settled via x402 USDC on Arc.

## GET /api/x402/research

Deep web research on any question: a multi-source scan (Jina / DuckDuckGo / Exa /
Tavily) that returns a verified brief plus cited sources. **\$0.01 per question**,
settled via Circle Gateway x402 in USDC on Arc Testnet (`eip155:5042002`).

No API key, no account — payment IS the authentication.

### Parameters

| Param   | In    | Required | Constraints    | Description            |
| ------- | ----- | -------- | -------------- | ---------------------- |
| `q`     | query | yes      | min 4 chars    | The research question. |
| `limit` | query | no       | 1–8, default 5 | Max sources scanned.   |

### 402 handshake

An unpaid request returns HTTP **402** with a base64 `PAYMENT-REQUIRED` header:

```bash theme={null}
curl -si "https://api.pulsmarket.tech/api/x402/research?q=will+the+Fed+cut+rates+in+September"
```

Decoded requirements (verified live):

```json theme={null}
{
  "x402Version": 2,
  "resource": {
    "url": "/api/x402/research",
    "description": "Deep web research on any question: multi-source scan (Jina/DDG/Exa/Tavily), verified brief + cited sources. Settled in USDC on Arc.",
    "mimeType": "application/json"
  },
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:5042002",
    "asset": "0x3600000000000000000000000000000000000000",
    "amount": "10000",
    "payTo": "0xa93FFcC230d1bd6f6b0a23a7f8BEcc2C9ECD894e",
    "maxTimeoutSeconds": 691200,
    "extra": {
      "name": "GatewayWalletBatched",
      "version": "1",
      "verifyingContract": "0x0077777d7EBA4688BDeF3E311b846F25870A19B9"
    }
  }]
}
```

Retry the request with the signed payload in a `payment-signature` header
(base64 JSON). On success you get **200 OK**, the resource, and a base64
`PAYMENT-RESPONSE` settlement header.

### Easiest client — Circle CLI

```bash theme={null}
circle services pay \
  "https://api.pulsmarket.tech/api/x402/research?q=will+the+Fed+cut+rates+in+September" \
  --address <AGENT_WALLET_ADDRESS> --chain ARC-TESTNET
```

### Success response

```json theme={null}
{
  "ok": true,
  "query": "will the Fed cut rates in September",
  "brief": "…multi-paragraph verified brief…",
  "sources": [{ "title": "…", "url": "https://…" }],
  "count": 5,
  "note": "Sourced brief generated by the Puls research pipeline. Settled via Circle Gateway x402 on Arc Testnet."
}
```

### Errors

| Status | Reason                                                                           |
| ------ | -------------------------------------------------------------------------------- |
| `400`  | `q` missing or shorter than 4 chars                                              |
| `402`  | No / invalid `payment-signature`, or settlement failed (`reason` field explains) |
| `500`  | Research pipeline failure (`detail` field)                                       |

Notes: the route enforces an internal 55s deadline, so partial results beat a
gateway timeout. Discovery of every paid Puls endpoint: `GET /api/bazaar`,
specs at `/openapi/index.json`.