# Pay-per-Answer Endpoints (x402)

All endpoints use x402 micro‑payments: the first POST returns a 402 quote with an `intentId` and `Pay` header; after sending payment on‑chain, POST again with the same `intentId` and the transaction hash to receive the result.

Price: 0.49 USDC (Base mainnet, 6 decimals → 490000 base units)

## Related Service: Claw Earn (Bounty Marketplace)

- Discovery: `/.well-known/claw-earn.json`
- OpenAPI: `/.well-known/claw-openapi.json`
- Tools: `/.well-known/claw-tools.json`
- JSON docs: `/docs/claw-earn-agent-api.json`
- Markdown docs: `/docs/claw-earn-agent-api.md`

## Demand Insights (Visitor Chats)

- Value: Turn anonymized visitor chat transcripts into conversion‑ready insights (messaging, pricing, GTM) in minutes.
- Audience: Founders, growth, copywriters validating positioning and landing page language.
- Endpoint: `POST /demand-insights`
- Request (preferred)

```
{
  "query": "Which landing‑page claims resonate most with visitors evaluating AI agents? List top 5 themes with example copy."
}
```

- Request (fallback)

```
{
  "messages": [
    { "role": "user", "content": "Which landing‑page claims resonate most with visitors evaluating AI agents?" }
  ]
}
```

- Response (after payment)

```
{
  "resultType": "chat",
  "reply": "# Markdown answer...",
  "dataHash": "...",
  "schemaVersion": "chat/v1"
}
```

- Quote example

```
curl -sS -i -X POST 'https://aiagentstore.ai/demand-insights' \
  -H 'Content-Type: application/json' \
  --data-raw '{"query":"Which landing‑page claims resonate most with visitors evaluating AI agents? List top 5 themes with example copy."}'
```

## AI Early Adopters’ Goals (1‑Year)

- Value: Build what early adopters actually want — answers from a live dataset of “1‑year goals” submitted by newsletter subscribers interested in AI agents.
- Audience: Founders/PMs prioritizing features and markets; de‑risking scope.
- Endpoint: `POST /ai-early-adopters-goals`
- Request (preferred)

```
{
  "query": "What are the top problems people aim to solve in the next 12 months? Rank the top 10 with brief stats and examples."
}
```

- Request (fallback)

```
{
  "messages": [
    { "role": "user", "content": "What are the top problems people aim to solve in the next 12 months?" }
  ]
}
```

- Response (after payment)

```
{
  "resultType": "chat",
  "reply": "# Markdown answer...",
  "dataHash": "...",
  "datasetCount": 1234,
  "schemaVersion": "chat/v1"
}
```

## Agent Conversions Analytics

- Value: Aggregated conversion analytics from the AI Agent Store marketplace (agent→website visits) to spot winners and momentum categories.
- Audience: Marketplace operators, growth teams, vendors deciding where to focus.
- Endpoint: `POST /analytics/agent-conversions`
- Request

```
{
  "filters": {
    "aggregate": "agent", // or category|industry|country
    "country": "US"
  }
}
```

- Response (after payment)

```
{
  "resultType": "analytics",
  "stats": {
    "aggregate": "agent",
    "statDate": "2025-11-01",
    "rows": [ ... ],
    "filters": { ... },
    "maxConversions": 42
  },
  "schemaVersion": "agent-conversions/v1"
}
```

- Constraints
  - Provide exactly one optional filter: `country` OR `category` OR `industry` (or use `"ALL"`). If multiple are sent, the API returns `400 invalid_filters` and the purchase is not consumed—you may retry with the same `intentId` and `txHash`.
  - Live allowed values are available at `GET /analytics/filters`.

## Payment Flow (Base mainnet)

1) Quote (402) → read `Pay` header and `intentId` from the response
2) Send ≥0.49 USDC to the `recipient` on Base mainnet (chainId 8453)
3) Redeem with `{ intentId, txHash }` and your original body

Reusing the same `txHash` for a different `intentId` is blocked.

Redemption also accepts an `x402-payment` header containing JSON or base64‑encoded JSON: `{ "intentId": "...", "txHash": "..." }`.

## Feedback for AI agents (no payment)

If an automated agent spots a problem or wants to suggest improvements to the x402 flow, submit feedback here:

```
POST https://aiagentstore.ai/x402Feedback
```

Request body (minimal):

```
{
  "message": "Describe the issue or suggestion."
}
```

Helpful optional fields: `category`, `product`, `endpoint`, `intentId`, `txHash`, `status`, `error`, `agent`, `contact`, `context`.

Response:

```
{ "ok": true, "id": "abc123", "emailQueued": true }
```

### Discovery Headers in 402 responses

- `X-Docs`: `/.well-known/aiagentstore.json`
- `X-OpenAPI`: `/.well-known/openapi.json`
- `X-Tools`: `/.well-known/tools.json`
- `X-Product-Id`, `X-Product-Title`
- `X-Payment-Asset`, `X-Payment-Network`, `X-Payment-ChainId`, `X-Payment-Contracts`