Perplexity Search

---
name: perplexity-search
description: Use this skill when the user wants a grounded web answer or research from Perplexity without an API key — e.g. "search the web for <topic>", "what's the latest on <topic>", "pull cited web context on <X>", "research <topic> with sources", "do a deep-research report on <X>". Runs Perplexity's x402 `/search` endpoint (with agent-answer and async deep-research escalations) paid per call through the SELAT Router from your Circle Gateway balance. The agent synthesizes the paid results into a cited brief.
license: Apache-2.0
compatibility: Requires the selat CLI, selat-pay >= 0.12.0 (for `--live-probe`), and a funded Circle Gateway balance (settles on whichever supported chain the balance sits on). The routed step needs a reachable SELAT Router (SELAT_ROUTER_URL); `selat skill verify --live-probe` (without --pay) is free and needs no funded wallet.
metadata:
  author: SELAT-AI
  version: "1.0"
  rail: x402 on Base
  kind: single
---

# perplexity-search

Grounded web search and research via **Perplexity's x402 endpoints**, fronted by the
paysponge gateway and **routed through the SELAT Router**. The default paid step is the
cheap `POST /search` (live quote $0.0105) — it returns ranked web results with page content and
source URLs, which the agent synthesizes into a cited answer. Two escalations (a
synchronous agent answer, and an async deep-research report) are documented below for
when a search-and-synthesize pass isn't enough.

## When To Use

Use when the user wants a **grounded, cited web read** — "what's the latest on X",
"research X with sources", "web context on X" — and you'd otherwise reach for an
external search API or tell them to get a Perplexity key. Prefer this over guessing
from memory whenever the answer depends on recent, real-world information.

Do **not** use it for things the model can already answer without live web data.

## Rails

Single paid step, native x402, routed through the SELAT Router (rail label
`x402 on Base`):

- **x402 on Base** — Perplexity `POST /search` (`pplx.x402.paysponge.com`) resolves as
  `mode=routed-x402`. The merchant's 402 accepts plain x402 `exact` (no Circle
  Gateway batching), so the SELAT Router pays that leg. You pay the router from your
  funded Circle Gateway balance, on whichever supported chain it sits. The label
  names the merchant's rail, not your pay chain. Live quote $0.0105 (2026-10-04).

## Workflow

1. Install: `selat skill install perplexity-search`
2. **Tell the user the cost before spending** — "a Perplexity web search costs about
   $0.01 from your wallet — go ahead?" — and proceed only on a yes.
3. Run the default search step:
   `selat skill run perplexity-search --query "<topic>" --recency month`
4. The CLI compiles the step into one `selat-pay` call and prints the JSON result.
5. **Synthesize, don't dump.** Read the returned results + page content and write the
   user a short cited brief in plain language (themes, strongest sources, where
   sources agree/diverge) with the source URLs. Keep raw JSON and the endpoint URL out
   of what you show the user.

### Escalations (agent-run; not part of the default step)

These use the same wallet/rail but are **not** wired as manifest steps — the async
flow needs a poll loop the linear runner can't express. Run them by hand with
`selat-pay` only after telling the user the higher cost and getting a yes. Exact
bodies are in [`references/endpoints.md`](references/endpoints.md).

- **Agent answer (~$0.01, ✓ verified):** `POST /v1/agent` with
  `{"input":"…","preset":"fast-search"}` returns a synthesized answer with live
  search results in one call. **Requires `input` plus one of `model`/`models`/`preset`**
  (the OpenAPI wrongly marks only `input` required). This is the cheap synchronous
  escalation for a one-call answer.
- **Deep research (~$0.01 + minutes):** `POST /v1/async/sonar` with
  `{"request":{"model":"sonar-deep-research","messages":[…]}}` returns a task `id`;
  then poll `GET /v1/async/sonar/{id}` (**free**) every ~15s until `status:"COMPLETED"`
  and read `response.choices[0].message.content` + `response.search_results`.

## Inputs And Outputs

| Param | Required | Default | Description |
|---|---|---|---|
| `query` | yes | none | The web search query. No default, so a missing query is refused instead of paying for a canned search. |
| `recency` | no | `month` | Recency filter: `hour` \| `day` \| `week` \| `month` \| `year`. |

Output: JSON with an array of web results (title, URL, page content/snippets) that the
agent reads and synthesizes into a cited brief.

## Gotchas

- **This gateway settles the payment before the upstream validates the body**, so a
  malformed request still costs the full price. The schemas here are pinned from the
  gateway's own OpenAPI (`/openapi.json`) — send exactly these shapes.
- **`/search` uses `query` (string or array); do not add integer fields via `${param}`.**
  The skill runner substitutes params as **strings only** (no type coercion), so a
  numeric field like `max_results` wired through `${…}` would send `"8"` and 4xx. Keep
  string-typed fields in the manifest body; adjust integer options only in a hand-built
  `selat-pay` call.
- **Async body wraps the request.** `POST /v1/async/sonar` needs
  `{"request":{model,messages}}` — a raw completion object (no `request` wrapper) 4xxs.
- **Async is `sonar-deep-research`-only.** `POST /v1/async/sonar` rejects `model:"sonar"`
  ("Async processing is only available for sonar-deep-research"). For a non-deep-research
  answer, use `/v1/agent` or `/search` instead.
- **`/v1/sonar` (synchronous chat) is intentionally omitted** — its paid call fails with
  `HTTP 431` (charged-but-not-delivered) until the upstream/router header issue is fixed
  (see repo issue #51). Don't add it back as a step.
- **`recency` must be one of** `hour|day|week|month|year`; any other value 4xxs (and costs).
- **The poll GET is free** (`mode=routed-free`, $0) — poll as often as needed at no cost.
- `idempotency_key` is accepted on `/v1/async/sonar` — reuse the same key to avoid
  double-submitting a costly deep-research task on a retry.

## Validation

> `--chain base` below is only the flag `selat-pay` requires for a probe — probing reads a free, chain-independent quote and never settles. A paid run resolves the settlement chain from your funded Circle Gateway balance, not the manifest.

- Static: `selat skill validate ./skills/perplexity-search`
- Live gate (free, probe-only): `selat skill verify ./skills/perplexity-search --live-probe --query "agentic payments adoption"`
- Single-step probe (no pay): confirms rail + price without settling:
  ```bash
  selat-pay POST "https://pplx.x402.paysponge.com/search" \
    --body '{"query":"agentic payments adoption","search_recency_filter":"month"}' \
    --chain base --probe-only --live-probe
  ```
  A served endpoint prints `detected: x402=yes … mode=routed-x402` and `price=$0.010500`.
  The network printed beside the price echoes the probe's `--chain` token. It is not
  your settlement chain.
- Paid run prints `status=200` and the results JSON.

## References

- `manifest.json` — the machine-readable payment recipe this skill runs.
- [`references/endpoints.md`](references/endpoints.md) — full request schemas for all 5 Perplexity endpoints (enriched from the gateway OpenAPI).
- [`references/agent-skill-authoring-sop.md`](../../references/agent-skill-authoring-sop.md) — authoring standard.
- selat-pay — https://github.com/SELAT-AI/selat-pay