# AlphaPipeline

> Pay-per-call ($0.005-$0.03 USDC) market data API for AI agents and trading bots. No signup, no API key, no OAuth - authenticate and pay in a single request via the x402 protocol (HTTP 402) on Base.

AlphaPipeline is a machine-first data API. Every endpoint below is metered per call using x402: a request without a payment header gets back a standard HTTP 402 response describing exactly how to pay (asset, amount, network, recipient), using an EIP-3009 `transferWithAuthorization` signature - no account creation, no dashboard, no API key issuance. Sign, retry the request with the payment attached, and you get the data back in the same request/response cycle.

This service is also indexed on the [x402 Bazaar](https://www.x402bazaar.org/) discovery layer, so x402-aware agent frameworks can find and call it without ever reading this file. This file exists for agents and crawlers that discover services by reading `llms.txt` directly.

## Payment spec

- Protocol: x402 (HTTP 402 Payment Required), scheme `exact`
- Network: Base mainnet, `eip155:8453`
- Asset: USDC (`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`)
- Price: tiered by data value, not flat - see the per-endpoint price below each entry
- Settlement: Coinbase CDP (Developer Platform) Facilitator
- Protocol reference: https://docs.x402.org

If you are using an official or third-party x402 client SDK, you do not need anything below except the endpoint paths and query parameters - your client already knows how to parse a 402 response and retry with payment; the exact price for each call is always authoritative in that 402 response, not in this file.

## Endpoints

### GET https://alphapipeline-eu.onrender.com/v1/market/kimchi-alert — $0.01 USDC/call

Use this when you need to know whether a cryptocurrency is trading at a premium or discount on Korean exchanges (Upbit) versus the global market, commonly called the "kimchi premium." Also use it to detect a reverse premium (possible localized crash risk) or a fast intraday premium surge.

- Query params: `symbol` (string, optional, default `BTC`) - e.g. `BTC`, `ETH`, `SOL`
- Example request: `GET /v1/market/kimchi-alert?symbol=BTC`
- Example response:
```json
{
  "generated_at": {"utc": "2026-09-02T12:00:00Z", "kst": "2026-09-02 21:00:00 KST"},
  "symbol": "BTC",
  "upbit_price_krw": 145000000.0,
  "binance_price_usdt": 108000.5,
  "usdkrw_rate_estimate": 1345.2,
  "kimchi_premium_pct": 0.15,
  "premium_change_1h_pct": 0.42,
  "alerts": {"reverse_premium": false, "premium_surge_1h": false},
  "thresholds": {"reverse_premium_pct": -1.5, "surge_1h_pct": 3.0}
}
```
- Do NOT call this for non-Korean-exchange comparisons or for historical/backtesting data - this is a live snapshot only.

### GET https://alphapipeline-eu.onrender.com/v1/tools/ai-markdown — $0.005 USDC/call

Use this when you need the actual text content of a webpage but want to avoid burning tokens on HTML tags, ads, navigation, and scripts - or when raw HTML is causing hallucinations downstream. Call it before summarizing or extracting facts from any arbitrary URL.

- Query params: `url` (string, required) - full http(s) URL to convert
- Example request: `GET /v1/tools/ai-markdown?url=https://example.com`
- Example response:
```json
{
  "url": "https://example.com",
  "title": "Example Domain",
  "markdown": "# Example Domain\n\nThis domain is for use in illustrative examples in documents.",
  "char_count": 87
}
```
- Do NOT call this for pages requiring login/authentication, or for non-HTML resources (PDFs, binaries, images) - not supported.

### GET https://alphapipeline-eu.onrender.com/v1/unlocks/dump-risk — $0.03 USDC/call (premium alpha data)

Use this when you need to assess whether a token carries dumping risk from token unlocks or ongoing vesting schedules - before entering a position, when screening a token list, or when asked "is this token safe from unlocks." Returns tokens whose currently-locked or unlock-eligible supply exceeds a materiality threshold (default 3% of circulating supply), each with a computed `risk_level` (LOW/MEDIUM/HIGH).

- Query params: none
- Example request: `GET /v1/unlocks/dump-risk`
- Example response:
```json
{
  "generated_at": {"utc": "2026-09-03T12:00:00Z", "kst": "2026-09-03 21:00:00 KST"},
  "supply_pct_threshold": 3.0,
  "protocols_scanned": 87,
  "count": 1,
  "unlocks": [
    {
      "token": "UNI",
      "unlock_supply_pct": 4.8,
      "unlock_amount": 28500000.0,
      "days_until_unlock": null,
      "timing_precision": "pending_schema_verification",
      "risk_level": "MEDIUM",
      "category": "onchain_vesting_stream (unclassified)",
      "data_source": "onchain_sablier"
    }
  ],
  "data_source": "onchain_sablier",
  "coverage_notice": "Scanned via on-chain Sablier vesting streams only. Absence from this list does not mean a token has no lockup."
}
```
- IMPORTANT: `days_until_unlock: null` means "unlock timing is currently unknown," not "no risk." Never treat a null value as a safety signal.
- Coverage is limited to tokens using supported on-chain vesting mechanisms - always read the `coverage_notice` field in the live response before concluding a token is unlock-free.

## Quick test (no wallet required)

```bash
curl "https://alphapipeline-eu.onrender.com/v1/market/kimchi-alert?symbol=BTC"
```
This returns a standard HTTP 402 response with the exact payment instructions (no charge is made) - useful for confirming the protocol is live before wiring up a paying client.

## More info

- Interactive docs (Swagger UI): https://alphapipeline-eu.onrender.com/docs
- Machine-readable OpenAPI spec: https://alphapipeline-eu.onrender.com/openapi.json
- Service root / health: https://alphapipeline-eu.onrender.com/