GP Stakes MPP Gateway

Private markets intelligence for AI agents — pay per call in TON.

GP Stakes indexes 6,051 GP profiles, 8,822 fund performance records, 6,069 Oracle scores, 128 GP stakes deals, 23,238 BDC positions, and 165,539 RE transactions. This gateway exposes that data to AI agents via the Machine Payments Protocol (MPP) — pay-per-call access using TON.

Why This Exists

Pitchbook charges $20,000+/year. Preqin charges $15,000+/year. These are annual subscriptions designed for human analysts.

AI agents need a different model: pay for what you use, per API call. GP Stakes MPP charges 0.01–0.5 TON per call (~$0.02–$1.00), with no subscription, no commitment, and no human in the loop.

Architecture

┌──────────────┐     402 / data      ┌──────────────────┐    proxy    ┌──────────────────┐
│   AI Agent   │ ←──────────────────→ │  MPP Gateway     │ ─────────→ │  GP Stakes API   │
│  (any LLM)   │   X-Payment-Proof   │  :8800           │            │  :8000           │
└──────┬───────┘                      └────────┬─────────┘            └──────────────────┘
       │                                       │
       │  pay TON                              │  verify tx
       ▼                                       ▼
┌──────────────┐                      ┌──────────────────┐
│  TON Network │                      │  TON Center API  │
│  (testnet)   │                      │  (verification)  │
└──────────────┘                      └──────────────────┘

MPP Protocol Flow

1. Agent:  GET /api/search?q=blackstone
2. Server: 402 Payment Required
           {
             "x402Version": 1,
             "accepts": [{
               "network": "ton-testnet",
               "recipient": "EQD...",
               "amount": "10000000",
               "asset": "TON",
               "description": "GP Stakes directory search"
             }],
             "endpoint": "/api/search?q=blackstone",
             "validFor": 600
           }
3. Agent:  sends 0.01 TON to recipient on TON testnet
4. Agent:  GET /api/search?q=blackstone
           Header: X-Payment-Proof: {"txHash": "<hash>", "network": "ton-testnet"}
5. Server: verifies tx on-chain → returns data

Pricing

Quick Start

# Install dependencies
pip install -r requirements.txt

# Copy and edit config
cp .env.example .env

# Run
uvicorn main:app --host 0.0.0.0 --port 8800

# Verify
curl http://localhost:8800/mpp/supported
curl http://localhost:8800/api/search?q=blackstone  # → 402

Endpoints

Free (no payment required)

• GET / — Service info
• GET /health — Health check
• GET /docs — OpenAPI docs
• GET /mpp/supported — Full service catalog with pricing
• GET /mpp/pricing — Compact pricing table
• GET /mpp/usage — Usage statistics

Paid (402 → pay → verify → data)

• GET /api/search?q=<query> — Search directory
• GET /api/fund/<fund_id> — Fund details
• GET /api/fund/<fund_id>/performance — Fund performance time series
• GET /api/oracle/<gp_name> — Oracle score + components
• GET /api/oracle — Leaderboard
• GET /api/deals?gp=<name>&type=<gp_stake|bdc> — Deal listings
• GET /api/deals/<deal_id> — Deal details
• GET /api/graph?from=<entity>&relation=<type> — Knowledge graph

Agent Integration Example

import httpx
import json

BASE = "http://localhost:8800"

# 1. Discover available data
catalog = httpx.get(f"{BASE}/mpp/supported").json()
print(f"Endpoints: {len(catalog['endpoints'])}")

# 2. Try a query → get 402
resp = httpx.get(f"{BASE}/api/search", params={"q": "blackstone"})
assert resp.status_code == 402
payment_info = resp.json()

# 3. Pay TON (pseudo-code — use your TON SDK)
tx_hash = send_ton(
    to=payment_info["accepts"][0]["recipient"],
    amount=int(payment_info["accepts"][0]["amount"]),
    network="ton-testnet",
)

# 4. Retry with proof
resp = httpx.get(
    f"{BASE}/api/search",
    params={"q": "blackstone"},
    headers={"X-Payment-Proof": json.dumps({"txHash": tx_hash, "network": "ton-testnet"})},
)
assert resp.status_code == 200
data = resp.json()
print(f"Found {data['total']} results")

Production Features

• Strict TON verification — every payment verified on-chain via TON Center API
• Transaction replay protection — each txHash can only be used once
• Per-payer rate limiting — sliding window per sender address
• Usage tracking — SQLite-backed billing log (sender, endpoint, amount, timestamp)
• Upstream proxy — forwards to real GP Stakes API at localhost:8000
• Mock fallback — returns representative data when upstream is unavailable
• Proper error taxonomy — distinct error codes (payment_required, invalid_proof, tx_already_used, rate_limited)

Configuration

All settings via environment variables (see .env.example):

Testing

python3 -m pytest tests/ -v

Project Structure

/opt/gpstakes-mpp/
├── main.py              # FastAPI app with lifespan
├── config.py            # Settings from env
├── mpp/
│   ├── middleware.py     # Payment gate middleware
│   ├── verify.py        # On-chain TON tx verification
│   ├── pricing.py       # Pricing tiers
│   ├── usage.py         # Billing, replay protection, rate limiting
│   ├── proxy.py         # Upstream API proxy
│   └── types.py         # Pydantic models
├── routes/
│   ├── discovery.py     # /mpp/* — catalog, pricing, usage
│   ├── search.py        # /api/search
│   ├── fund_data.py     # /api/fund/*
│   ├── oracle.py        # /api/oracle/*
│   ├── deals.py         # /api/deals/*
│   ├── graph.py         # /api/graph
│   └── _mock.py         # Mock data (fallback)
├── data/
│   └── usage.db         # SQLite billing database (auto-created)
├── tests/
│   └── test_mpp.py      # 29 tests
├── requirements.txt
├── .env.example
└── README.md