# magent

Paid clinical ground truth for autonomous medical agents. USDC on Base via x402 V2. No API keys.
Not a medical device. Do not send patient names or MRNs.

Base URL: https://api.magentlab.com
Human docs: https://api.magentlab.com/docs

## Discover

- Catalog: GET https://api.magentlab.com/v1/catalog
- OpenAPI: GET https://api.magentlab.com/openapi.json
- Manifest: GET https://api.magentlab.com/.well-known/x402
- This file: GET https://api.magentlab.com/llms.txt
- Full params: GET https://api.magentlab.com/llms-full.txt
- Human docs: GET https://api.magentlab.com/docs
- CDP Bazaar merchant: payTo=0x33236133BecE789D551d0B5c4f9A50095d4b57d3

## Pay (x402 V2)

1. GET the tool with `Accept: application/json` (do not send `Accept: text/html` unless you want the human paywall).
2. HTTP 402. Decode the base64 `PAYMENT-REQUIRED` header.
3. Retry the same URL with `PAYMENT-SIGNATURE` (base64 JSON echoing `accepted`, `payload`, and `extensions` when present).
4. Success is HTTP 200 JSON plus `PAYMENT-RESPONSE`. Settlement happens before the tool runs.

## Playbook: Prior authorization coding

Job: turn a chart phrase into a current ICD-10-CM or RxNorm code. Do not guess codes from training data.

1. GET https://api.magentlab.com/api/ontology/translate?query=Tylenol%20500mg&system=rxnorm

## Playbook: Oncology dosing arithmetic

Job: Mosteller BSA from height and weight. Do not let a model multiply.

1. GET https://api.magentlab.com/api/calc/bsa_mosteller?height_cm=170&weight_kg=70

## Ontology translation

GET /api/ontology/translate
Price: $0.005 USDC (5000 atomic) on eip155:8453
Example: https://api.magentlab.com/api/ontology/translate?query=Tylenol%20500mg&system=rxnorm
Human docs: https://api.magentlab.com/docs/ontology

- query (query, required): Natural-language drug, diagnosis, or lab description. Max 512 characters. Do not send patient names.
- system (query, optional, enum rxnorm|icd10|loinc): Restrict to rxnorm, icd10 (ICD-10-CM), or loinc. Omit to search all.
- tty (query, optional, enum SCD|SBD|IN|PIN|MIN|BN|GPCK|BPCK|DF|SCDC|SBDC|SCDF|SBDF|CM|LN): Restrict term type. Pharmacy orders typically want SCD. ICD-10-CM is CM; LOINC is LN.
- limit (query, optional, default 5): Number of ranked matches to return (1-25). Default 5.
- min_score (query, optional, default 35): Minimum rank score 0-100. Default 35.
- include_obsolete (query, optional, default false): Include deprecated/obsolete codes. Default false.
- billable_only (query, optional, default true): ICD-10-CM: return only HIPAA billable codes, not headers. Default true.

- HTTP 400 invalid_query: query is required and must be 1-512 characters
- HTTP 400 invalid_system: system must be rxnorm, icd10, or loinc
- HTTP 400 invalid_tty: tty must be a known RxNorm, ICD-10-CM, or LOINC term type
- HTTP 400 invalid_limit: limit must be an integer from 1 to 25
- HTTP 400 invalid_min_score: min_score must be an integer from 0 to 100
- HTTP 402 payment_required: Missing or invalid PAYMENT-SIGNATURE; decode the PAYMENT-REQUIRED header
- HTTP 409 payment_in_progress: The same authorization nonce is already being settled; retry shortly
- HTTP 429 rate_limited: Too many requests from this client
- HTTP 503 settlement_uncertain: Settlement is unconfirmed; retry with the same PAYMENT-SIGNATURE
- HTTP 503 facilitator_unavailable: Payment facilitator unavailable
- HTTP 503 facilitator_misconfigured: Payment facilitator is not configured
- HTTP 503 facilitator_unauthorized: Payment facilitator rejected credentials
- HTTP 503 ledger_unavailable: Payment ledger unavailable
- HTTP 503 payment_unavailable: Payment processing unavailable

Example 200 (fixture):

{
  "system": "rxnorm",
  "matches": [
    {
      "code": "198440",
      "status": "current",
      "system": "rxnorm",
      "display": "acetaminophen 500 MG Oral Tablet",
      "tty": "SCD",
      "obsolete": false,
      "billable": null,
      "score": 95
    }
  ],
  "query": "Tylenol 500mg",
  "disclaimer": "Not a medical device. Deterministic published-formula or coded-ontology output for autonomous agents. A licensed clinician remains responsible for patient care and billing submissions.",
  "catalog": {
    "coverage": "full",
    "icd10cm_fy": "FY2026-04",
    "license": {
      "icd10cm": "ICD-10-CM from CMS/NCHS. US claims codes, not WHO ICD-10.",
      "loinc": "This material contains content from LOINC (http://loinc.org). LOINC is copyright © Regenstrief Institute, Inc. and the Logical Observation Identifiers Names and Codes (LOINC) Committee and is available at no cost under the license at http://loinc.org/license. LOINC® is a registered United States trademark of Regenstrief Institute, Inc.",
      "rxnorm": "This product uses publicly available data courtesy of the U.S. National Library of Medicine (NLM), National Institutes of Health, Department of Health and Human Services; NLM is not responsible for the product and does not endorse or recommend this or any other product."
    },
    "loinc_version": "2.82",
    "notes": "ICD-10 entries are ICD-10-CM (US claims), not WHO ICD-10. RxNorm is Current Prescribable Content until a licensed full monthly ingest lands.",
    "rxnorm_release": "2026-08-03",
    "source": "postgres ingest",
    "systems": [
      "rxnorm",
      "icd10",
      "loinc"
    ],
    "version": "icd10:FY2026-04|loinc:2.82|rxnorm:2026-08-03"
  },
  "match_count": 1,
  "match_quality": "high"
}

## Mosteller BSA

GET /api/calc/bsa_mosteller
Price: $0.005 USDC (5000 atomic) on eip155:8453
Example: https://api.magentlab.com/api/calc/bsa_mosteller?height_cm=170&weight_kg=70
Human docs: https://api.magentlab.com/docs/bsa

- height_cm (query, optional): Height in centimeters. Provide height_cm or height_in.
- weight_kg (query, optional): Weight in kilograms. Provide weight_kg or weight_lb.
- height_in (query, optional): Height in inches. Converted as cm = in * 2.54.
- weight_lb (query, optional): Weight in pounds. Converted as kg = lb * 0.45359237.

- HTTP 400 invalid_height: height_cm (50-250) or height_in (20-98) is required
- HTTP 400 invalid_weight: weight_kg (1-500) or weight_lb (2-1100) is required
- HTTP 402 payment_required: Missing or invalid PAYMENT-SIGNATURE; decode the PAYMENT-REQUIRED header
- HTTP 409 payment_in_progress: The same authorization nonce is already being settled; retry shortly
- HTTP 429 rate_limited: Too many requests from this client
- HTTP 503 settlement_uncertain: Settlement is unconfirmed; retry with the same PAYMENT-SIGNATURE
- HTTP 503 facilitator_unavailable: Payment facilitator unavailable
- HTTP 503 facilitator_misconfigured: Payment facilitator is not configured
- HTTP 503 facilitator_unauthorized: Payment facilitator rejected credentials
- HTTP 503 ledger_unavailable: Payment ledger unavailable
- HTTP 503 payment_unavailable: Payment processing unavailable

Example 200 (fixture):

{
  "disclaimer": "Not a medical device. Deterministic published-formula or coded-ontology output for autonomous agents. A licensed clinician remains responsible for patient care and billing submissions.",
  "citation": {
    "authors": "Mosteller RD",
    "doi": "10.1056/NEJM198710223171717",
    "id": "mosteller-1987",
    "source": "N Engl J Med. 1987;317(17):1098",
    "title": "Simplified calculation of body-surface area"
  },
  "formula": "mosteller",
  "formula_expression": "BSA_m2 = sqrt((height_cm * weight_kg) / 3600)",
  "bsa_m2": 1.8181,
  "height_cm": 170.0,
  "weight_kg": 70.0
}

## CKD-EPI 2021 eGFR

GET /api/calc/egfr_ckd_epi
Price: $0.005 USDC (5000 atomic) on eip155:8453
Example: https://api.magentlab.com/api/calc/egfr_ckd_epi?creatinine_mg_dl=1.1&age=65&sex=female
Human docs: https://api.magentlab.com/docs/egfr

- creatinine_mg_dl (query, optional): Serum creatinine in mg/dL. Provide this or creatinine_umol_l.
- creatinine_umol_l (query, optional): Serum creatinine in µmol/L. Converted as mg/dL = µmol/L / 88.42.
- age (query, required): Age in years (18-120). CKD-EPI 2021 is validated in adults.
- sex (query, required, enum female|male): Sex used by the published equation. female or male.

- HTTP 400 invalid_creatinine: creatinine_mg_dl (0.1-20) or creatinine_umol_l (9-1768) is required
- HTTP 400 invalid_age: age must be an integer from 18 to 120
- HTTP 400 invalid_sex: sex must be female or male
- HTTP 402 payment_required: Missing or invalid PAYMENT-SIGNATURE; decode the PAYMENT-REQUIRED header
- HTTP 409 payment_in_progress: The same authorization nonce is already being settled; retry shortly
- HTTP 429 rate_limited: Too many requests from this client
- HTTP 503 settlement_uncertain: Settlement is unconfirmed; retry with the same PAYMENT-SIGNATURE
- HTTP 503 facilitator_unavailable: Payment facilitator unavailable
- HTTP 503 facilitator_misconfigured: Payment facilitator is not configured
- HTTP 503 facilitator_unauthorized: Payment facilitator rejected credentials
- HTTP 503 ledger_unavailable: Payment ledger unavailable
- HTTP 503 payment_unavailable: Payment processing unavailable

Example 200 (fixture):

{
  "units": "mL/min/1.73m2",
  "disclaimer": "Not a medical device. Deterministic published-formula or coded-ontology output for autonomous agents. A licensed clinician remains responsible for patient care and billing submissions.",
  "age_years": 65,
  "citation": {
    "authors": "Inker LA, Eneanya ND, Coresh J, et al.",
    "doi": "10.1056/NEJMoa2102953",
    "id": "inker-2021",
    "source": "N Engl J Med. 2021;385(19):1737-1749",
    "title": "New Creatinine- and Cystatin C-Based Equations to Estimate GFR without Race"
  },
  "creatinine_mg_dl": 1.1,
  "egfr_ml_min_1_73m2": 55.8,
  "formula": "ckd_epi_2021_creatinine",
  "formula_expression": "142 * min(Scr/κ,1)^α * max(Scr/κ,1)^(-1.200) * 0.9938^age * (1.012 if female)",
  "sex": "female"
}

## CHA2DS2-VASc

GET /api/calc/cha2ds2_vasc
Price: $0.005 USDC (5000 atomic) on eip155:8453
Example: https://api.magentlab.com/api/calc/cha2ds2_vasc?age=78&sex=female&chf=false&hypertension=true&diabetes=true&stroke_tia=false&vascular_disease=false
Human docs: https://api.magentlab.com/docs/cha2ds2-vasc

- age (query, required): Age in years (18-120). ≥75 scores 2; 65-74 scores 1.
- sex (query, required, enum female|male): female scores 1 (Sc); male scores 0.
- chf (query, required): Congestive heart failure or LV dysfunction. true or false.
- hypertension (query, required): Hypertension history. true or false.
- diabetes (query, required): Diabetes mellitus. true or false.
- stroke_tia (query, required): Prior stroke, TIA, or thromboembolism. true or false (2 points).
- vascular_disease (query, required): Prior MI, peripheral artery disease, or aortic plaque. true or false.

- HTTP 400 invalid_age: age must be an integer from 18 to 120
- HTTP 400 invalid_sex: sex must be female or male
- HTTP 400 invalid_flag: chf, hypertension, diabetes, stroke_tia, and vascular_disease must be true or false
- HTTP 402 payment_required: Missing or invalid PAYMENT-SIGNATURE; decode the PAYMENT-REQUIRED header
- HTTP 409 payment_in_progress: The same authorization nonce is already being settled; retry shortly
- HTTP 429 rate_limited: Too many requests from this client
- HTTP 503 settlement_uncertain: Settlement is unconfirmed; retry with the same PAYMENT-SIGNATURE
- HTTP 503 facilitator_unavailable: Payment facilitator unavailable
- HTTP 503 facilitator_misconfigured: Payment facilitator is not configured
- HTTP 503 facilitator_unauthorized: Payment facilitator rejected credentials
- HTTP 503 ledger_unavailable: Payment ledger unavailable
- HTTP 503 payment_unavailable: Payment processing unavailable

Example 200 (fixture):

{
  "components": [
    {
      "factor": "congestive_heart_failure",
      "points": 0,
      "present": false
    },
    {
      "factor": "hypertension",
      "points": 1,
      "present": true
    },
    {
      "value": 78,
      "factor": "age",
      "points": 2,
      "present": true
    },
    {
      "factor": "diabetes",
      "points": 1,
      "present": true
    },
    {
      "factor": "stroke_tia_thromboembolism",
      "points": 0,
      "present": false
    },
    {
      "factor": "vascular_disease",
      "points": 0,
      "present": false
    },
    {
      "factor": "sex_female",
      "points": 1,
      "present": true
    }
  ],
  "disclaimer": "Not a medical device. Deterministic published-formula or coded-ontology output for autonomous agents. A licensed clinician remains responsible for patient care and billing submissions.",
  "age_years": 78,
  "citation": {
    "authors": "Lip GYH, Nieuwlaat R, Pisters R, Lane DA, Crijns HJ",
    "doi": "10.1378/chest.09-1584",
    "id": "lip-2010",
    "source": "Chest. 2010;137(2):263-272",
    "title": "Refining clinical risk stratification for predicting stroke and thromboembolism in atrial fibrillation using a novel risk factor-based approach: the euro heart survey on atrial fibrillation"
  },
  "formula": "cha2ds2_vasc",
  "sex": "female",
  "max_score": 9,
  "score": 5
}

Do not call GET /v1/tools/ping for production work; it is a payment smoke test only.