TrialPath Agent API

A read API for autonomous agents over the universal ClinicalTrials.gov mirror. Every condition. Every sponsor. Every site. Parkinson's disease trials get an extra layer of AI-curated summaries.

x402 USDC on base OpenAPI MCP

1. Pick how you want to call it

There are four ways to use the API. Pick whichever fits your use case. You can mix them on the same key.

Order of preference for paid calls: free daily quota first, then prepaid credits, then per-call x402.

2. Get a free API key

The free key takes about 10 seconds. Pass an email, complete the bot check, and you'll get a key with a daily free quota.

3. Quickstart (REST)

Free, no key required

curl "https://parkinsonspathways.com/api/agent/v1/llms-index"

Free with a key (counts against your daily quota)

curl -H "X-API-Key: $KEY" \
  "https://parkinsonspathways.com/api/agent/v1/trials/search?q=parkinson&limit=5"

Paid, anonymous (x402 USDC)

curl -i "https://parkinsonspathways.com/api/agent/v1/trials/NCT04201093/snapshot"
# Returns 402 Payment Required with x402 paymentRequirements.
# Sign with an x402-aware client and replay with X-PAYMENT.
# Note: /trials/search, /trials/{nctId}/brief, and /field-changes require
# an API key (401 without one) even when you intend to pay per call.

4. Patient match (any condition)

Rank trials for a structured patient profile across any condition. Hard disqualifiers (age, sex, healthy-volunteer, exclusion-criteria conflicts on comorbidities, prior treatments, or excludeTerms) drop trials entirely. Remaining trials get a normalised fit score from 0 to 1 across the dimensions you supply: location, travel, biomarkers, placebo tolerance, phase, study type, sponsor preference, drug classes, intervention kinds, performance status, required terms.

Price: $0.10 per call (free under daily quota).

curl -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{
    "condition": "breast cancer",
    "age": 54,
    "sex": "female",
    "biomarkers": ["HER2+", "BRCA1"],
    "phasePreference": ["PHASE2", "PHASE3"],
    "acceptsPlacebo": false,
    "locationRegion": "us",
    "state": "California",
    "travelPreference": "can_travel"
  }' \
  "https://parkinsonspathways.com/api/agent/v1/match"

5. Catalyst Calendar

Forward-looking calendar of trial milestones across the universal mirror: primary completion dates, status changes, and stale signals. Filter by date window, condition, sponsor, phase, drug class, country. Built for biotech analysts and trading desks.

Price: $0.05 per call (free under daily quota).

curl -H "X-API-Key: $KEY" \
  "https://parkinsonspathways.com/api/agent/v1/catalysts?from=2026-01-01&to=2026-06-30&condition=oncology"

6. Endpoints and pricing

Full OpenAPI: /api/agent/v1/openapi.json
Machine index: /api/agent/v1/llms-index
Mirror Markdown twin: /agent/trials/{nctId}.md

7. Prepaid credits

Top up a balance once over x402. Every paid call automatically debits credits before falling back to per-call USDC. Bonus credit on top-ups starts at 10% and scales to 33%. So an Enterprise top-up of $5,000 lands as $6,650 of API calls. No Stripe. No monthly subscription. No expiry.

Reads (GET /credits/balance, GET /credits/transactions) are free with an API key. Top-up uses x402 at POST /api/agent/v1/credits/topup?tier=growth. The server demands the exact USDC amount registered for that tier (a payer cannot pay $10 and claim $5,000). On-chain tx hashes are unique-constrained, so a replayed payment is rejected.

8. Use over MCP (Claude Desktop, Cursor, Cline)

The same handlers are exposed as a Model Context Protocol server at POST /mcp. Install manifest: /mcp.json.

Server name: trialpath. Tools available: search_trials, get_trial_brief (free basic / paid full), get_llms_index, get_field_changes, match_patient (any condition), get_sponsor_activity, get_investigator_activity, replay_trial_snapshot, subscribe_to_changes, get_catalysts, plus prepaid-credit utilities (list_topup_tiers, get_credit_balance, get_credit_transactions, topup_credits).

Each tool's MCP schema includes its price_usd, rest_endpoint, and x402_network in _meta, so agents can surface cost before invoking.

One-click install

Install in Cursor Install in VS Code Install manifest (mcp.json)

Cursor and VS Code support deep-link MCP installs. Click a button above to open the editor with the server pre-configured. After install, paste your X-API-Key into the server's headers.

Manual install

Claude Desktop: add to ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "trialpath": {
      "transport": "streamable-http",
      "url": "https://parkinsonspathways.com/mcp",
      "headers": { "X-API-Key": "<your-key>" }
    }
  }
}

Cursor: add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "trialpath": {
      "url": "https://parkinsonspathways.com/mcp",
      "headers": { "X-API-Key": "<your-key>" }
    }
  }
}

MCP shares quota and payments with REST. Use the same X-API-Key for free daily-quota calls. To pay per call, pass X-PAYMENT on the HTTP POST to /mcp. When a paid call has no payment and no quota, the tool returns the x402 paymentRequirements as structuredContent, so an x402-aware client can sign and retry.

9. Errors, rate limits, and SLAs

• 200: success.
• 400: invalid request body or query parameters. Response includes a Zod-style issues array.
• 401: this endpoint requires a key (writes, subscriptions, credits reads).
• 402: payment required. The body is x402 paymentRequirements for the exact USDC amount and network. Sign and replay with X-PAYMENT.
• 404: unknown NCT id or unknown sponsor/investigator slug.
• 429: per-IP or per-key rate limit hit. Back off and retry.
• 500: server error. Safe to retry with the same idempotency conditions.

Per-IP rate limit applies to anonymous calls. Per-key rate limit is generous; the daily free quota is the binding constraint for keyed calls. The server runs on Replit autoscale on Base mainnet for x402 settlement. Network is always reported in /llms-index.

10. FAQ

Do I need an API key? Only if you want a daily free quota, prepaid credits, or to call write endpoints (subscriptions, top-ups). Anonymous read access works for the free tier of endpoints; everything else returns 402 if you do not pay.

What is "free tier"? A daily allowance of paid endpoints, given to you for free if you authenticate with a key. The key is how the server counts your free calls. Without a key the server cannot attribute the calls to anyone, so paid endpoints just return 402.

Can I pay without a key? For most paid endpoints, yes — send the request without a key, get a 402 with x402 paymentRequirements, sign, and replay with X-PAYMENT. Three high-volume data routes (/trials/search, /trials/{nctId}/brief, and /field-changes) are the exception: they require an API key and return 401 without one, even if you intend to pay per call. Request a free key first, then pay per call (or use your free daily quota).

Do you accept Stripe / credit cards? No. Settlement is USDC over x402 on Base. This keeps the API agent-native and removes the chargeback surface.

Are MCP and REST priced the same? Yes. The MCP server proxies the REST handlers internally, so the same usage row is written and the same price is charged.

How fresh is the mirror? The universal CT.gov mirror runs nightly at 02:00 ET. Field-level diffs (status changes, site adds, eligibility edits, etc.) are written per upsert and surfaced via /since, /field-changes, and the /catalysts calendar.

11. Legal

Privacy Policy · Terms of Service · Contact: spencer@parkinsonspathways.com