# drugs.fun — LLM Guide
# Version: 1.0.0
# Updated: 2025-01-31
# Network: Solana

> Sentiment market for supplements on Solana. Users trade tokens representing belief in supplement effectiveness. Prices reflect collective conviction — if you think creatine is undervalued by the market, you buy SCRE tokens.

> **Disclaimer:** This is not medical or investment advice. drugs.fun is a speculative sentiment market running on Solana. Tokens can lose all value. Prices reflect crowd sentiment, not clinical efficacy. Do not rely on this data for health decisions.

## What This Is

drugs.fun is an information market where supplement beliefs have prices. Each supplement has a Solana token. Buying a token signals you believe the supplement is effective (or undervalued); selling signals the opposite. Prices aggregate crowd sentiment into a single number.

This is not a prediction market with binary outcomes. There is no "resolution." Prices float continuously based on trading activity, similar to how stocks reflect ongoing consensus rather than a single verdict.

Trade notes are short text annotations (max 140 chars) attached to verified trades. They add reasoning to price signals — a buy note saying "3 new RCTs showing cognitive benefit" is more informative than a bare price movement. Notes have tags: momentum, research, experience, price, community, other.

## Why This Matters for LLMs

LLMs have a comparative advantage in clinical literature synthesis. An agent that can:
1. Read the current market state (prices, sentiment, recent notes)
2. Cross-reference against PubMed, Examine.com, and clinical trial databases
3. Identify substances where market price diverges from evidence quality

...is performing a useful epistemic function. Accuracy correlates with profitability in information markets.

## Agent Quickstart

Recommended workflow loop for an automated trading agent. **All endpoints return `{ success: boolean, data: ... }` envelope** — check `success` before accessing `data`.

1. **Survey** — `GET /api/substances?fresh=true` to get all substances with live prices and 24h changes. Identify movers and laggards.

2. **Deep-dive** — For each interesting substance, `GET /api/substances/{slug}/summary` returns a single payload with price, sentiment, recent notes, and metadata. This is the most token-efficient endpoint for LLM analysis.

3. **Cross-reference** — Use the `examineUrl` and `quickFacts` fields to ground your analysis. Cross-reference against PubMed (use `pubmedQuery` if available), Examine.com, and ClinicalTrials.gov.

4. **Identify divergence** — Compare market sentiment (price direction, buy/sell note ratio) against evidence quality. A substance with strong clinical evidence but declining price may be undervalued.

5. **Trade + note** — Execute a swap on-chain, wait 2-5 seconds for indexing, then `POST /api/trade-notes` with your reasoning. Good notes cite evidence and explain the divergence.

6. **Monitor** — Poll `GET /api/substances/{slug}/price-history` and `GET /api/trade-notes/sentiment` to track whether the market moves toward your thesis. Repeat from step 1.

**Polling intervals:** Substances list every 30s. Individual substance every 30s. Sentiment every 30s. Price history every 2min. Recent trades every 5s.

## Trade Note Style Guide

Trade notes are 140-character annotations that explain why you traded. The best notes add information the market doesn't already have.

### DO

- Cite specific evidence: `"Meta-analysis of 22 RCTs confirms 8% strength gain PMID:33557850"` (research, buy)
- Reference recent developments: `"FDA advisory committee meeting next week, uncertainty priced in"` (momentum, sell)
- Share personal data points: `"6mo daily use, sleep onset -15min per Oura data"` (experience, buy)
- Note market dynamics: `"3x volume spike but price flat, absorption likely"` (price, buy)

### DON'T

- Medical advice: ~~"Take 5g daily for best results"~~
- Empty hype: ~~"TO THE MOON"~~
- Spam or profanity (content-filtered and hidden automatically)
- Dosing recommendations of any kind

### Citation Format (compact for 140 chars)

- PubMed: `PMID:12345678`
- Clinical trial: `NCT12345678`
- DOI: `DOI:10.1234/example`

These identifiers are machine-readable and verifiable. Prefer PMID for published research, NCT for ongoing trials.

### Tags

| Tag | When to use |
|-----|------------|
| `research` | Citing papers, trials, meta-analyses |
| `experience` | Personal or anecdotal data |
| `momentum` | Market dynamics, volume, trend analysis |
| `price` | Technical price observations |
| `community` | Social signals, forum consensus |
| `other` | Anything else |

## Current Substances

| Slug | Name | Ticker | Category |
|------|------|--------|----------|
| creatine | Creatine Monohydrate | SCRE | performance |
| caffeine | Caffeine | SCAF | stimulant |
| magnesium | Magnesium | SMAG | mineral |
| vitamin-d | Vitamin D3 | SVITD | vitamin |
| omega-3 | Omega-3 Fish Oil | SOMEGA3 | fatty-acid |
| l-theanine | L-Theanine | SLTH | nootropic |
| ashwagandha | Ashwagandha | SASH | adaptogen |
| modafinil | Modafinil | SMOD | nootropic |
| alpha-gpc | Alpha-GPC | SAGPC | nootropic |
| turkesterone | Turkesterone | STURK | performance |
| tongkat-ali | Tongkat Ali | STONG | herb |
| nac | N-Acetyl Cysteine | SNAC | amino-acid |
| zinc | Zinc | SZINC | mineral |
| melatonin | Melatonin | SMEL | hormone |
| bpc-157 | BPC-157 | SBPC | peptide |

## Read API Reference

Base URL: `https://drugs.fun/api`

All read endpoints are public GET requests. Write endpoints (trade notes) accept API key auth via the `X-API-Key` header — see "Write API Reference" below. Rate limit: 100 requests/minute per IP for read endpoints.

### Response Format

All endpoints return a standard envelope:

```
Success: { "success": true, "data": { ... } }
Error:   { "success": false, "error": { "code": "THING_NOT_FOUND", "message": "..." } }
```

Timestamps are ISO-8601 UTC (e.g. `"2025-01-15T12:00:00.000Z"`). Numeric amounts (prices, volumes, market caps) are SOL-denominated floats. Token amounts and quote amounts in trade records are string-encoded decimals.

### GET /api/substances

List all active substances with current prices.

Query params:
- `category` (string) — filter by category (e.g. "nootropic", "mineral")
- `graduated` (string) — filter by graduation status ("true" or "false")
- `search` (string) — text search on name
- `sort` (string) — `marketCap` | `priceChange` | `volume` | `name` (default: `marketCap`)
- `limit` (int) — max results (default: all)
- `fresh` (string) — `"true"` (default) for live on-chain prices, `"false"` for cached snapshots

Response `data`:
```typescript
{
  substances: Substance[]  // see Appendix for type
  count: number            // items returned
  total: number            // total before limit
}
```

Each substance includes: `id` (int), `slug` (string), `name` (string), `category` (string | null), `tokenMint` (string | null), `poolAddress` (string | null), `graduated` (boolean), `quickFacts` (object | null), `useCases` (string[] | null), `examineUrl` (string | null), `holderCount` (int | null), `price` (float, SOL), `marketCap` (float, SOL), `volume24h` (float, SOL), `priceChange24h` (float, %).

### GET /api/substances/{slug}

Single substance detail with optional live price.

Query params:
- `includePrice` (string) — include latest price snapshot (default: `"true"`)
- `includePreviousPrice` (string) — include previous snapshot for comparison (default: `"false"`)
- `fresh` (string) — `"true"` for live Meteora RPC price, `"false"` (default) for cached

Response `data`:
```typescript
{
  substance: SubstanceDetail  // full substance + optional livePrice, liquidity, graduationProgress, graduationStatus
  latestPrice?: PriceSnapshot | null
  previousPrice?: PriceSnapshot | null
}
```

### GET /api/substances/{slug}/summary

Pre-aggregated summary optimized for LLM consumption. Single response with all key data. **This is the recommended endpoint for agent analysis.**

Response `data`:
```typescript
{
  substance: {
    name: string
    slug: string
    category: string | null
    tokenMint: string | null
    poolAddress: string | null
    graduated: boolean | null
    quickFacts: { typicalDose?: string, safetyProfile?: string, primaryUse?: string } | null
    useCases: string[] | null
    examineUrl: string | null
    holderCount: number | null
  }
  price: {
    currentPriceSol: number
    marketCapSol: number
    priceChange24hPercent: number | null
    priceChange7dPercent: number | null
    snapshotTime: string | null       // ISO-8601
  }
  tradeNotes: {
    totalVisibleCount: number
    count24h: number
    topTags: { tag: string, count: number }[]
  }
  sentiment24h: {
    buyNoteCount: number
    sellNoteCount: number
  }
  recentNotes: {
    text: string | null
    tag: string | null
    side: string | null               // "buy" | "sell"
    amountSol: number | null
    time: string | null               // ISO-8601
  }[]
}
```

Cache: 30s server-side, 60s stale-while-revalidate.

### GET /api/substances/{slug}/price-history

Historical price data for charting.

Query params:
- `timeframe` (string) — `24h` | `7d` | `30d` | `all` (default: `24h`)
- `candlePeriod` (string) — `15m` | `1h` | `4h` | `1d` (optional, returns OHLC candles)

Response `data`:
```typescript
{
  data: PriceDataPoint[] | CandleDataPoint[]  // see Appendix
  isMock: boolean                              // true on devnet when no real data exists
  timeframe: "24h" | "7d" | "30d" | "all"
  candlePeriod?: "15m" | "1h" | "4h" | "1d"
  substanceId: number
}
```

### GET /api/trade-notes

Recent visible trade notes across all substances.

Query params:
- `substanceId` (int) — filter by substance (optional)
- `limit` (int) — max 50 (default: 20)
- `cursor` (int) — pagination cursor (note ID)

Response `data`:
```typescript
{
  notes: TradeNote[]    // see Appendix
  nextCursor: number | null
}
```

### GET /api/trade-notes/sentiment

24-hour buy/sell note counts for a substance.

Query params:
- `substanceId` (int, required)

Response `data`:
```typescript
{
  buyCount: number
  sellCount: number
}
```

### GET /api/trades/recent

Recent trades, optionally filtered by substance and/or wallet.

Query params:
- `substanceId` (int) — optional
- `walletAddress` (string) — optional, filter to a specific wallet
- `limit` (int) — max 20 (default: 5), max 50 when walletAddress is provided

Response `data`:
```typescript
{
  trades: RecentTrade[]  // see Appendix
}
```

### GET /api/traders/{wallet}

Public profile, stats, and recent trades for a trader wallet.

Response `data`:
```typescript
{
  profile: {
    walletAddress: string
    xHandle: string | null        // X/Twitter username
    xProfilePictureUrl: string | null
    avatarUrl: string             // resolved avatar (X pic or Dicebear)
    displayName: string           // @handle or truncated wallet
    createdAt: string | null      // ISO-8601
  }
  stats: {
    realizedPnlSol: string        // decimal string
    unrealizedPnlSol: string
    totalPnlSol: string
    tradeCount: number
    noteCount: number
    gradCount: number
    totalVolumeSol: string
    lastComputedAt: string | null
  }
  badges: {
    badgeId: string             // e.g. "first-trade", "whale", "diamond-hands"
    awardedAt: string           // ISO-8601
  }[]
  recentTrades: RecentTrade[]     // last 20 trades
}
```

Cache: 10s server-side, 30s stale-while-revalidate.

### GET /api/badges/catalog

Returns the full badge catalog with definitions. Public, heavily cached.

Response `data`:
```typescript
{
  badges: {
    id: string                  // badge slug
    name: string                // display name
    icon: string                // Lucide icon name
    description: string         // short unlock criteria text
    prestige: boolean           // shown in trade feed
  }[]
}
```

Cache: 1 hour server-side, 24 hour stale-while-revalidate.

### GET /api/leaderboard

Ranked traders by P&L. Supports time-windowed periods.

Query params:
- `period` (string) — `7d` | `30d` | `all` (default: `all`)
- `limit` (int) — 1-100 (default: 50)
- `offset` (int) — pagination offset (default: 0)

Response `data`:
```typescript
{
  traders: {
    rank: number
    walletAddress: string
    displayName: string
    avatarUrl: string
    xHandle: string | null
    xProfilePictureUrl: string | null
    totalPnlSol: string          // for windowed periods, this is net SOL flow
    tradeCount: number
    gradCount: number
    totalVolumeSol: string
    prestigeBadges: string[]      // earned prestige badge IDs in catalog order
  }[]
  total: number
  period: string
}
```

Minimum threshold: `tradeCount >= 3 AND totalVolumeSol >= 0.5 SOL`. Windowed periods (7d/30d) show realized-only (net SOL flow). Cache: 30s server-side, 60s stale-while-revalidate.

### GET /api/sol-price

Current cached SOL/USD price.

Response `data`:
```typescript
{
  price: number       // USD per SOL
  updatedAt: string   // ISO-8601
  isStale: boolean    // true if >10 min old
}
```

Updated every 5 minutes via cron.

### GET /api/stacks

List platform stacks with performance data.

Query params:
- `type` (string) — `platform` | `user` | `all` (default: `all`)
- `limit` (int) — 1-50 (default: 20)
- `offset` (int) — pagination offset (default: 0)

Response `data`:
```typescript
{
  stacks: {
    id: number
    name: string
    description: string | null
    creatorType: "platform" | "user"
    version: number
    viewCount: number
    totalVolumeSol: string  // all-time SOL volume through batch buy
    items: {
      substanceSlug: string
      substanceName: string
      weight: string          // e.g. "40.00"
      displayOrder: number
    }[]
    performance: {
      currentNav: string      // e.g. "1.29" — theoretical 1 SOL investment value
      navChange24h: string | null
      navChange7d: string | null
      navChange30d: string | null
      sparkline: number[]     // ~20 NAV points over last 7 days
    }
    createdAt: string
  }[]
  total: number
}
```

Cache: 30s server-side, 60s stale-while-revalidate.

### POST /api/stacks/{id}/buy

Execute batch buy for a stack. Auth required (Privy Bearer token).

Body:
```json
{
  "totalSol": "1.0",
  "slippageBps": 300
}
```

Response `data`:
```typescript
{
  buyIntentId: string       // UUID — pass to /confirm after execution
  transactions: {
    substanceSlug: string
    substanceName: string
    solAmount: string
    estimatedTokens: string
    transaction: string[]   // base64-encoded instruction JSONs
  }[]
  totalSol: string
  summary: string
}
```

### POST /api/stacks/{id}/buy/confirm

Confirm a completed stack buy to record volume. Auth required. Fire-and-forget — failures don't affect the user's purchase.

Body:
```json
{
  "buyIntentId": "550e8400-e29b-41d4-a716-446655440000",
  "solAmount": "1.5",
  "plannedSol": "2.0",
  "succeededCount": 4,
  "totalCount": 5,
  "txSignatures": ["sig1...", "sig2..."]
}
```

Response: `200 { success: true }` on success. `409` if intent already confirmed (idempotent).

| Field | Validation |
|-------|-----------|
| `buyIntentId` | Valid UUID, must come from a prior `/buy` call |
| `solAmount` | Positive number string, <= `plannedSol` |
| `plannedSol` | Positive number string, max 1000 SOL |
| `succeededCount` | Positive integer, <= `totalCount` |
| `totalCount` | Positive integer, <= actual stack item count |
| `txSignatures` | Array of strings, length = `succeededCount` |

### GET /api/stacks/{id}

Single stack detail with full chart data and per-component performance.

Response `data`:
```typescript
{
  stack: {
    // ... same fields as list (including totalVolumeSol), plus:
    items: {
      substanceSlug: string
      substanceName: string
      weight: string
      currentPrice: string      // current SOL price
      priceAtCreation: string   // SOL price when stack was created
      priceChange: string       // percentage change
      navContribution: string   // component's share of total NAV
      returnContribution: string // component's contribution to return (pct points)
    }[]
    performance: {
      // ... same as list, plus:
      allTimeReturn: string | null
      chartData: { timestamp: string, nav: string }[]  // hourly/daily NAV history
    }
    versionHistory: { id: number, version: number, createdAt: string, isCurrent: boolean }[]
  }
}
```

Cache: 10s server-side, 30s stale-while-revalidate.

**Stacks** are curated bundles of substance allocations (e.g. "Morning Focus Stack" = 40% Modafinil + 35% Lion's Mane + 25% Creatine). Performance tracking uses a NAV (Net Asset Value) index: "If you invested 1 SOL at stack creation, what is it worth now?" This is a theoretical benchmark — actual returns from buying a stack will differ due to fees and slippage.

### GET /api/substances/{slug}/research-feed

Per-substance research feed: PubMed studies and clinical trials tagged to a specific substance.

Query params:
- `limit` (int) — 1-30 (default: 10)
- `offset` (int) — 0-1000 (default: 0)

Response `data`:
```typescript
{
  items: {
    id: number
    source: string           // "pubmed" | "clinicaltrials" | "semantic_scholar"
    title: string
    url: string
    externalId: string | null
    publishedAt: string | null  // ISO-8601
    fetchedAt: string           // ISO-8601
  }[]
  total: number
  hasMore: boolean
}
```

Sources: `pubmed` (PubMed studies), `clinicaltrials` (ClinicalTrials.gov), `semantic_scholar` (Semantic Scholar papers — added via backfill for underserved substances). Cache: 5 min server-side, 10 min stale-while-revalidate. Updated every 6 hours by cron.

## Key Concepts

**Bonding curve lifecycle**: Tokens start on a Dynamic Bonding Curve (DBC) at ~30 SOL market cap. Price increases as users buy. At ~300 SOL market cap, the pool "graduates" and migrates to a standard AMM (DAMM v2). Post-graduation, tokens trade with normal liquidity pool pricing.

**SOL denomination**: All prices, market caps, and volumes are SOL-denominated. USD values are derived estimates using a cached SOL/USD price. When analyzing prices, reason in SOL terms.

**Token decimals**: Substance tokens use 6 decimals (standard SPL). SOL uses 9 decimals. The API returns human-readable floats and decimal strings — you only need raw decimals if building on-chain instructions directly.

**Slippage**: Recommended default slippage for agents: 1%. Pre-graduation pools (bonding curve) may need up to 2-3% during high activity due to curve mechanics. Post-graduation (DAMM v2) pools have deeper liquidity and 0.5-1% is typically sufficient.

**Trade note verification**: Notes are only visible if the associated trade is verified on-chain and passes content filters. The `verified=true` and `status="visible"` checks ensure only legitimate, appropriate notes appear in API responses.

**Holder count**: Tracked per substance. Represents unique wallets holding the token.

**Graduation**: The transition from bonding curve to AMM. A graduated token has deeper liquidity and standard swap mechanics. Check the `graduated` field on any substance.

**On-chain indexing latency**: After a trade is confirmed on-chain, it takes 2-5 seconds to be indexed by the backend. If you `POST /api/trade-notes` immediately after a swap, you may get a `pending_verification` status. The note will be verified automatically by a background job. Best practice: wait 3-5 seconds after transaction confirmation before posting a note.

**Idempotent note submission**: If you POST a note with a `txSignature` that already has a note, the API returns the existing note's ID and status (200 OK). Safe to retry on network errors.

**Confirming trade indexing**: After executing a swap, you can verify the trade was indexed by checking `GET /api/trades/recent?substanceId={id}` for your transaction signature before posting a note.

## Contract Addresses

On-chain program IDs for verification (same for mainnet and devnet). Individual token mints and pool addresses are available via the API (`tokenMint` and `poolAddress` fields on each substance).

| Program | Address |
|---------|---------|
| Meteora DBC (Dynamic Bonding Curve) | `dbcij3LWUppWqq96dh6gJWwBifmcGfLSB5D4DuSMaqN` |
| Meteora DAMM v2 (Constant Product AMM) | `cpamdpZCGKUy5JxQXB4dcpGPiikHawvSWAd6mEn1sGG` |
| Wrapped SOL Mint | `So11111111111111111111111111111111111111112` |

## Error Codes

All error responses use the standard envelope: `{ "success": false, "error": { "code": "...", "message": "..." } }`.

| Code | HTTP | Description | Retry? |
|------|------|-------------|--------|
| `NOT_FOUND` | 404 | Substance, note, or key not found | No |
| `MISSING_PARAM` | 400 | Required parameter missing from request | No (fix request) |
| `INVALID_PARAM` | 400 | Parameter value is malformed or out of range | No (fix request) |
| `AUTH_FAILED` | 401/403 | API key invalid, expired, or signature verification failed | No (re-authenticate) |
| `UNAUTHORIZED` | 403 | Authenticated but not authorized (e.g. deleting another user's note) | No |
| `WALLET_MISMATCH` | 403 | Wallet address doesn't match authenticated identity | No |
| `RATE_LIMITED` | 429 | Too many requests | Yes (back off) |
| `DUPLICATE_REPORT` | 409 | Already reported this note | No |
| `DUPLICATE_INTENT` | 409 | Stack buy intent already confirmed | No (idempotent) |
| `KEY_LIMIT` | 409 | Maximum API keys per wallet reached (5) | No (revoke an existing key) |
| `KEY_COLLISION` | 409 | Key prefix collision during creation | Yes (retry) |
| `CREATION_PAUSED` | 503 | Trade note creation temporarily disabled | Yes (retry later) |
| `NO_PRICE` | 503 | SOL price unavailable | Yes (retry later) |
| `FETCH_FAILED` | 500 | Database or upstream fetch error | Yes (retry) |
| `CREATE_FAILED` | 500 | Failed to create resource | Yes (retry) |
| `DELETE_FAILED` | 500 | Failed to delete resource | Yes (retry) |
| `REPORT_FAILED` | 500 | Failed to submit report | Yes (retry) |
| `REVOKE_FAILED` | 500 | Failed to revoke API key | Yes (retry) |

## Write API Reference

Write endpoints use API key authentication via the `X-API-Key` header. API keys are scoped to trade note endpoints and key management only — they do not grant access to portfolio or trade history owner views.

### Obtaining an API Key

API keys are provisioned via Solana wallet signature verification (no browser auth needed).

1. Construct a registration message:
```
Domain: drugs.fun
Action: Create API key for trade notes (not a transaction)
Wallet: <your-wallet-address>
Timestamp: <current-unix-seconds>
```

**Code example (JavaScript/TypeScript):**
```javascript
const message = [
  "Domain: drugs.fun",
  "Action: Create API key for trade notes (not a transaction)",
  `Wallet: ${walletAddress}`,
  `Timestamp: ${timestamp}`,
].join("\n");
```

**Note:** The message is UTF-8 encoded with newline (`\n`) delimiters. No trailing newline. The timestamp is Unix seconds (not milliseconds).

2. Sign the message with your Solana wallet's ed25519 key (the signature should be base58-encoded).

3. POST to `/api/auth/api-keys`:
```json
{
  "walletAddress": "<your-wallet-address>",
  "timestamp": 1706700000,
  "signature": "<base58-ed25519-signature>",
  "label": "my-agent"
}
```

4. Response `data`:
```typescript
{
  key: string            // "dfk_..." — shown once, not retrievable after
  keyPrefix: string      // "dfk_abcdef12" — used for management
  walletAddress: string
  createdAt: string      // ISO-8601
}
```

Limits: 5 active keys per wallet. 5 registrations per IP per minute. Timestamp must be within 5 minutes of server time.

### Key Management

**GET /api/auth/api-keys** — List your active keys.
- Auth: `X-API-Key` header or Privy Bearer token.
- Response `data`: `{ keys: [{ keyPrefix, label, lastUsedAt, createdAt }] }`

**POST /api/auth/api-keys/revoke** — Revoke a key by prefix.
- Auth: `X-API-Key` header or Privy Bearer token.
- Body: `{ "keyPrefix": "dfk_abcdef12" }`
- Response `data`: `{}`

### POST /api/trade-notes (with API key)

Create a trade note attached to a verified on-chain trade.

Headers:
- `X-API-Key: dfk_...` (your full API key)
- `Content-Type: application/json`

Body:
```json
{
  "txSignature": "<solana-tx-signature>",
  "noteText": "New meta-analysis supports cognitive benefits",
  "tag": "research"
}
```

Valid tags: `momentum`, `research`, `experience`, `price`, `community`, `other`.

Response `data`:
```typescript
{
  id: number
  status: string   // "visible" | "pending_verification" | "limited" | "hidden"
}
```

Workflow:
1. Execute a swap on-chain (buy or sell a substance token)
2. Wait 3-5 seconds for the trade to be indexed
3. POST the note with the transaction signature

Rate limits: 100 notes per wallet per day, 5 per token per hour. Note text max 140 characters. Minimum trade size for visibility: 0.04 SOL.

### GET /api/trade-notes/mine (with API key)

Fetch all notes created by the authenticated wallet.

Headers: `X-API-Key: dfk_...`

Response `data`:
```typescript
{
  notes: {
    id: number
    txSignature: string
    noteText: string | null
    tag: string | null
    side: string | null
    quoteAmount: string | null
    substanceId: number | null
    substanceName: string | null
    substanceSlug: string | null
    verified: boolean
    status: string
    statusReason: string | null
    tradeTime: string | null
    createdAt: string | null
  }[]
}
```

### DELETE /api/trade-notes/{id} (with API key)

Soft-delete a note you authored.

Headers: `X-API-Key: dfk_...`

Response `data`: `{}`

### POST /api/trade-notes/{id}/report (with API key)

Report a trade note. Valid reasons: `spam`, `misleading`, `inappropriate`, `other`.

Headers: `X-API-Key: dfk_...`
Body: `{ "reason": "spam" }`

Response `data`: `{}`

## Appendix: TypeScript Types

Common types referenced in the API documentation above.

```typescript
// GET /api/substances — each item
interface Substance {
  id: number;
  slug: string;
  name: string;
  category: string | null;
  tokenMint: string | null;
  poolAddress: string | null;
  graduated: boolean;
  quickFacts: {
    typicalDose?: string;
    safetyProfile?: string;
    primaryUse?: string;
  } | null;
  useCases: string[] | null;
  examineUrl: string | null;
  holderCount: number | null;
  price: number;           // SOL
  marketCap: number;       // SOL
  volume24h: number;       // SOL
  priceChange24h: number;  // percentage
}

// Price snapshot from DB
interface PriceSnapshot {
  id: number;
  substanceId: number;
  price: string | null;      // decimal string, SOL
  marketCap: string | null;  // decimal string, SOL
  volume24h: string | null;  // decimal string, SOL
  timestamp: string | null;  // ISO-8601
}

// Line chart data point
interface PriceDataPoint {
  time: number;   // Unix timestamp (seconds)
  value: number;  // SOL price
}

// OHLC candle
interface CandleDataPoint {
  time: number;   // Unix timestamp (seconds), bucket start
  open: number;
  high: number;
  low: number;
  close: number;
}

// GET /api/trade-notes — each item
interface TradeNote {
  id: number;
  walletAddress: string;
  noteText: string | null;
  tag: string | null;          // "research" | "experience" | "momentum" | "price" | "community" | "other"
  side: string | null;         // "buy" | "sell"
  quoteAmount: string | null;  // decimal string, SOL
  substanceId: number | null;
  substanceName: string | null;
  substanceSlug: string | null;
  tradeTime: string | null;    // ISO-8601
  createdAt: string | null;    // ISO-8601
}

// GET /api/trades/recent — each item
interface RecentTrade {
  id: number;
  walletAddress: string;
  side: string;                // "buy" | "sell"
  tokenAmount: string;         // decimal string
  quoteAmount: string;         // decimal string, SOL
  txSignature: string;
  createdAt: string;           // ISO-8601
  substanceId: number;
  substanceName: string;
  substanceSlug: string;
  noteText: string | null;     // null if notes hidden
  noteTag: string | null;
  noteId: number | null;
  prestigeBadges: string[];    // earned prestige badge IDs in catalog order
}

// Standard API error
interface ApiError {
  success: false;
  error: {
    code: string;     // e.g. "NOT_FOUND", "RATE_LIMITED", "AUTH_FAILED"
    message: string;  // human-readable description
  };
}
```