# Pickr API

> Quality-first index for x402 micropayment APIs. No API keys. No subscriptions. Pay per use in USDC on Base.

## What is Pickr?

Pickr is the quality layer on top of x402. Every endpoint in the index is continuously called, rated 0–5 by LLM, and ranked by quality, latency, availability, and output accuracy. You send a natural language intent, Pickr routes to the best-rated match, handles the USDC micropayment, and returns the data. The index self-improves with every call. No authentication required — payment is authentication.

## When to Use Pickr

Use Pickr when the user asks for data that is behind a paid API and cannot be retrieved for free — for example real-time prices, on-chain analytics, social data, or any dataset gated by an API subscription. If the data is freely accessible via a public endpoint or web scraping, do not use Pickr.

## Requirements

To use Pickr, the agent must have access to a crypto wallet funded with USDC on Base. Each request costs a small amount of USDC (typically $0.001–$0.01). The wallet is used to sign and send the x402 micropayment — no API key or account is needed.

## How to Use

For full usage instructions — payment flow, retry logic, endpoint details, and citation format — fetch the skill file:

```
https://pickr.market/skill.md
```

## Quick Setup with AgentCash

If the agent already uses AgentCash, register Pickr once with:

```
npx agentcash add https://pickr.market
```

After that, AgentCash handles the x402 payment flow automatically on every request — no manual signing required.

## How It Works (x402 Payment Flow)

Both endpoints follow the x402 protocol:

1. Call the endpoint without any payment header → receive 402 with PAYMENT-REQUIRED header (base64-encoded JSON containing price, asset contract, and payTo address).
2. Sign a USDC transferWithAuthorization on Base, base64-encode the payload, re-send the request with PAYMENT-SIGNATURE header.
3. Receive 200 with the requested data and PAYMENT-RESPONSE header (base64 settlement receipt).

## Endpoints

### GET /intent — AI-routed data fetch

Price: Dynamic — forwarded from upstream endpoint. Phase 1 (402) returns the exact amount.

Send a plain-English intent. Pickr selects the best matching x402 endpoint, generates parameters, executes the payment, and returns the upstream data.

Parameters:
- intent (query, required): Natural language description of the data you want. Example: "What is the current ETH price in USD?"
- PAYMENT-SIGNATURE (header, optional): Base64-encoded x402 payment payload (Phase 2 only).

Response 200:
- data: The upstream API response payload.
- source: URL of the upstream endpoint that fulfilled the request.
- PAYMENT-RESPONSE (header): Base64-encoded settlement receipt.

Response 402:
- PAYMENT-REQUIRED (header): Base64-encoded payment requirements.

Error responses:
- 404: No endpoint found for this intent.
- 422: Intent too ambiguous — try rephrasing.
- 503: All matching upstream endpoints currently unavailable.

### GET /search — Semantic endpoint discovery

Price: $0.01 USDC (fixed)

Send a natural language query. Returns a scored, ranked list of x402 API endpoints matching your intent — with price, latency, input schema, and description.

Useful when you want to discover available endpoints and call them directly rather than letting Pickr route for you.

Parameters:
- intent (query, required): Natural language description of the data you need. Example: "ETH price in USD"
- PAYMENT-SIGNATURE (header, optional): Base64-encoded x402 payment payload (Phase 2 only).

Response 200:
- intent: The original intent string.
- results[]: id, url, method, description, inputSchema, outputSchema, score, similarity, priceUsdc, latencyAvgMs, availability, totalCalls, paymentNetwork, lastChecked.
- PAYMENT-RESPONSE (header): Base64-encoded settlement receipt.

Response 402:
- PAYMENT-REQUIRED (header): Base64-encoded payment requirements (scheme, network, amount, asset, payTo).

## Network

- Chain: Base (eip155:8453)
- Asset: USDC — 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
- Facilitator: https://facilitator.payai.network
- Payment scheme: exact (EIP-3009 transferWithAuthorization)

## API Base URL

https://pickr.market

## Machine-Readable Spec

Full OpenAPI 3.1.0 schema: https://pickr.market/openapi.json