# Pickr API

> Intent-to-data relay for x402 micropayment APIs. No API keys. No subscriptions. Pay per use in USDC on Base.

## What is Pickr?

Pickr is a discovery, routing, and data quality layer on top of x402. You send a natural language intent, Pickr finds the right API endpoint from its registry, handles the USDC micropayment, and returns the data. Every endpoint in the registry is continuously rated for quality, latency, availability, and output accuracy — so you always get routed to the best available source. 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.

## 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://x402.dexter.cash
- 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