# Pazieh Financial Intelligence API — Agent Guide

## Data Quality
- **Support/Resistance levels**: Production-grade. Consolidated from pivot clustering, reliable across all timeframes.
- **Pattern detection**: Experimental. Chart patterns (H&S, flags, etc.) are algorithmically detected and may produce false positives. Always validate with other indicators.

## Base URL
`https://pazieh.com`

## Authentication
None required for free endpoints. Rate limit: 30 requests/minute.

## x402 Micropayments
Premium endpoints require payment via the [x402 protocol](https://x402.org). Send a payment header with your request.

**Paid endpoints:**
| Endpoint | Price |
|----------|-------|
| `/ta/{symbol}` | $0.005 USDC |
| `/ta/batch/{symbols}` | $0.02 USDC |
| `/analysis/{symbol}` | $0.01 USDC |

**Payment details:**
- Network: Polygon (eip155:137)
- Currency: USDC
- Recipient: `0x3a9928bC92beBA99E20cFb7AfA1d5A85AD83560E`
- Facilitator: Self-hosted (auto-negotiated via 402 headers)

Without payment, these endpoints return HTTP 402 with payment requirements in the `payment-required` header.

**Free endpoints** (no payment needed): `/`, `/health`, `/price/{symbol}`, `/report/{symbol}`, `/chart-data/{symbol}`, `/docs`, `/docs/agent`, `/pricing`

## Endpoints

### `GET /analysis/{symbol}?interval=1d&multi_tf=false`
**Primary endpoint for AI agents.** Returns structured, actionable analysis.

**Parameters:**
- `symbol` (path) — Ticker symbol (e.g., `ETH-USD`, `AAPL`, `BTC-USD`)
- `interval` (query) — Timeframe: `1s|5s|15s|30s|1m|5m|15m|30m|1h|4h|1d|1wk` (sub-minute only for crypto via Binance) (default: `1d`)
- `multi_tf` (query) — Set `true` for multi-timeframe analysis (Weekly + Daily + 4H)

**Response structure:**
```json
{
  "symbol": "ETH-USD",
  "timestamp": "2026-02-21T17:00:00Z",
  "overall_bias": "bearish",          // Only with multi_tf=true
  "all_active_setups": [...],         // Only with multi_tf=true
  "timeframes": {
    "1d": {
      "price": 1987.05,
      "trend": "BEARISH (STRONG)",
      "rating": "SELL",
      "suggested_bias": "bearish",
      "indicators": {
        "rsi": 42.3,                  // <30 oversold, >70 overbought
        "macd_histogram": -12.5,      // >0 bullish, <0 bearish
        "adx": 28.5,                  // >25 strong trend
        "atr": 85.2,                  // Average True Range (volatility)
        "ema_alignment": "all_bearish" // all_bullish|mostly_bullish|mixed|mostly_bearish|all_bearish
      },
      "support_resistance": [
        {"price": 1900, "type": "support", "touches": 3, "distance_pct": -4.38}
      ],
      "active_setups": [
        {
          "type": "bear_pennant",
          "direction": "bearish",
          "confidence": 0.6,
          "outcome": "active",
          "setup": {
            "side": "short",
            "entry": 1906.82,
            "stop_loss": 2037.16,
            "take_profit": 1776.48,
            "risk_reward": 1.0,
            "trigger": "Break below lower trendline"
          }
        }
      ],
      "completed_patterns": [...],
      "candlestick_signals": [
        {"type": "doji", "direction": "neutral", "label": "✚ Doji"}
      ],
      "signals": ["MACD_BEARISH_CROSS"]
    }
  }
}
```

### How to use this data

**For trade decisions:**
1. Check `suggested_bias` (or `overall_bias` for multi-TF) for direction
2. Look at `active_setups` for specific trade entries with stop loss and targets
3. Validate with `indicators` (RSI extremes, ADX trend strength, EMA alignment)
4. Check `support_resistance` for nearby levels and `distance_pct` to gauge proximity
5. Use `candlestick_signals` as confirmation

**Setup fields explained:**
- `side`: "long", "short", or "range"
- `entry`: Price level to enter the trade
- `stop_loss`: Price to exit if trade goes wrong
- `take_profit`: Price target
- `risk_reward`: Reward / Risk ratio (higher is better, >2.0 is good)
- `trigger`: Human-readable condition for entry

**For range setups (rectangles):**
- Contains both `long_entry/stop_loss/take_profit` and `short_entry/stop_loss/take_profit`
- `current_position`: tells you if price is `near_support` or `near_resistance`

**Confidence scores:** 0.0 to 1.0. Volume-confirmed patterns get a boost. >0.7 = high confidence.

**Outcome values:**
- `active` — Pattern is forming or just completed, setup is live
- `hit` — Target was reached (historical)
- `failed` — Pattern failed (historical)

### Other endpoints
- `GET /ta/{symbol}?interval=1d` — Raw indicators only (lighter)
- `GET /ta/batch/{symbols}?interval=1d` — Batch analysis (up to 10 symbols, comma-separated)
- `GET /price/{symbol}` — Current price + OHLCV
- `GET /report/{symbol}` — Human-readable HTML report with interactive charts
- `GET /health` — API health check

### Rate Limits
30 requests/minute per IP. Data cached for 5 minutes.

### Tips for agents
- Use `multi_tf=true` for comprehensive analysis before major decisions
- Single timeframe is faster and cheaper — use for quick checks
- Check `distance_pct` on S/R levels to find nearby levels (within ±2% = imminent)
- Combine `active_setups` with `ema_alignment` for higher conviction trades
- `signals` array contains key technical events (crosses, squeezes, extremes)
API ONLINE