# Orisha Data MCP

Client-side MCP wrapper for the public Orisha Data x402 endpoints.

Orisha Data provides machine-readable market-data endpoints over HTTPS with x402 payment support. This wrapper lets an MCP-capable client inspect free previews and discovery documents before making paid x402 calls.

## Public Endpoints

Base URL: `https://orisha-data.com`

| Tool | Public endpoint | Price | Notes |
|------|-----------------|-------|-------|
| `orisha_docs` | `GET /docs` | Free | Machine-readable service docs. |
| `orisha_x402_discovery` | `GET /.well-known/x402` | Free | x402 resource discovery. |
| `orisha_signing_keys` | `GET /.well-known/orisha-signing-key.json` | Free | Public response-signing key set. |
| `orisha_c1_preview` | `GET /c1/preview/:pair` | Free | Unsigned sample for the C1 price endpoint. |
| `orisha_d1_preview` | `GET /d1/preview` | Free | Unsigned redacted D1 structure and freshness preview. |
| `orisha_c1_price` | `GET /c1/price/:pair` | $0.01 | Paid x402 crypto/FX price response. |
| `orisha_d1_levels` | `GET /d1/levels` | $0.07 | Paid x402 CME micro futures structural levels response. |

D1 coverage window: Monday-Friday, 09:30-16:10 America/New_York. During active market windows, D1 may refuse overly stale data before payment instead of charging for unusable data.

## Install

```bash
git clone https://github.com/OrishaAI/orisha-data-mcp.git
cd orisha-data-mcp
npm install
```

Run the free live smoke check:

```bash
npm run smoke
```

Run the MCP server over stdio:

```bash
npm run start
```

## MCP Client Configuration

Example client configuration:

```json
{
  "mcpServers": {
    "orisha-data": {
      "command": "node",
      "args": ["/absolute/path/to/orisha-data-mcp/src/server.mjs"],
      "env": {
        "ORISHA_DATA_BUYER_PRIVATE_KEY": "0xYOUR_BUYER_PRIVATE_KEY_PLACEHOLDER"
      }
    }
  }
}
```

The placeholder key above is intentionally not real. Use a buyer wallet only when you intend to call paid tools.

## Free Evaluation Flow

An evaluating agent can try the service without payment:

1. Call `orisha_docs` to read the public service documentation.
2. Call `orisha_x402_discovery` to inspect the paid resource list.
3. Call `orisha_c1_preview` with `BTC-USD`, `ETH-USD`, or `SOL-USD`.
4. Call `orisha_d1_preview` to inspect D1 freshness and redacted structure.
5. Call `orisha_signing_keys` to fetch the public key set used for paid response verification.

Equivalent direct HTTPS checks:

```bash
curl -s https://orisha-data.com/docs
curl -s https://orisha-data.com/.well-known/x402
curl -s https://orisha-data.com/c1/preview/BTC-USD
curl -s https://orisha-data.com/d1/preview
curl -s https://orisha-data.com/.well-known/orisha-signing-key.json
```

## Paid Usage

Paid tools require a buyer wallet private key in the MCP client process:

```bash
ORISHA_DATA_BUYER_PRIVATE_KEY=0xYOUR_BUYER_PRIVATE_KEY_PLACEHOLDER npm run start
```

Available paid tools:

- `orisha_c1_price`: calls the C1 paid price endpoint for a requested pair.
- `orisha_d1_levels`: calls the D1 paid levels endpoint.

Responses from paid tools may include `_signature`. Verify those signatures using the key set at `/.well-known/orisha-signing-key.json`.

## Response Signing

The public signing key set is available at:

```text
https://orisha-data.com/.well-known/orisha-signing-key.json
```

The key set currently contains `orisha-response-ed25519-v1`. Treat the endpoint as a key set from day one so future rotations can add keys without changing client assumptions.

## Safety

- This package is client-side only.
- Free tools do not require a buyer key.
- Paid tools require a buyer key and may spend USDC through x402.
- Do not put production buyer keys in examples, screenshots, issues, or logs.