# easy-predict

> Agent-first prediction and anomaly detection API. Send a list of numbers, get a prediction or anomaly report. $0.01 USDC per call on Base via x402 v2 micropayments.

## Usage

POST to a paid endpoint with a signed x402 v2 payment header. Omit the payment header to receive a 402 response containing exact payment terms — use those terms to construct and sign the payment payload, then retry.

---

## POST /timeseries — predict next value

Request body (object form):

```json
{"series": [1.0, 2.3, 4.1, 6.8, 9.2], "context": "monthly revenue in USD"}
```

- `series`: array of 3–1000 finite numbers (required)
- `context`: plain-text description of what the series represents, max 200 chars (optional)

Response:

```json
{
  "prediction": 12.1,
  "method": "linear",
  "holdout_errors": {"linear": 0.05, "log1p-linear": 0.31, "last-delta": 0.05, "mean": 3.5},
  "slope": 1.94,
  "intercept": 0.12,
  "context": "monthly revenue in USD"
}
```

- `method`: winning model — `linear`, `log1p-linear`, `last-delta`, or `mean`
- `holdout_errors`: absolute error of each candidate on the held-out last point
- `slope`, `intercept`: present only when method is `linear` or `log1p-linear`

---

## POST /anomaly-detection — detect anomalies via z-score

Request body (object form):

```json
{"series": [1.0, 2.3, 4.1, 6.8, 99.0], "threshold": 2.0, "context": "cpu usage %"}
```

- `series`: array of 3–1000 finite numbers (required)
- `threshold`: z-score cutoff, 0 < threshold ≤ 10, default 2.0 (optional)
- `context`: plain-text description of what the series represents, max 200 chars (optional)

Response:

```json
{
  "anomalies": [{"index": 4, "value": 99.0, "z_score": 2.14}],
  "method": "z-score",
  "mean": 15.12,
  "std": 39.18,
  "threshold": 2.0,
  "context": "cpu usage %"
}
```

`anomalies` is an empty array when no points exceed the threshold.

---

## Payment

- Network: Base (eip155:8453)
- Asset: USDC — 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
- Amount: $0.01 (10000 atomic units, 6 decimals)
- Facilitator: https://x402.org/facilitator
- Header: `PAYMENT-SIGNATURE: <base64-encoded signed x402 v2 PaymentPayload JSON>`

## Agent integration example

A working Claude agent that calls both endpoints and pays autonomously via x402 is available at:

https://github.com/rizzi-williams/easy-predict/blob/main/examples/demo_agent.py

The agent uses the Anthropic Python SDK with tool use. When a tool call hits a 402, it parses the payment challenge, signs a payment payload, and retries with the `PAYMENT-SIGNATURE` header — no human in the loop. The same pattern works in any agentic framework that supports custom tool implementations (LangChain, LlamaIndex, CrewAI, AutoGen, etc.).

```python
pip install anthropic requests eth-account
ANTHROPIC_API_KEY=... WALLET_PRIVATE_KEY=... python examples/demo_agent.py
```

---

## Endpoints

- [POST /timeseries](https://easy-predict.com/timeseries): Predict the next value in a numeric series using automatic model selection (linear, log1p-linear, last-delta, mean). Requires x402 v2 payment.
- [POST /anomaly-detection](https://easy-predict.com/anomaly-detection): Detect anomalies in a numeric series via z-score. Requires x402 v2 payment.
- [GET /.well-known/x402](https://easy-predict.com/.well-known/x402): Machine-readable x402 v2 resource list and payment requirements.
- [GET /openapi.json](https://easy-predict.com/openapi.json): Full OpenAPI 3.1 specification.
- [GET /llms.txt](https://easy-predict.com/llms.txt): This document.