# Hamilton depression rating scale

HAM-D

Status: LIVE
Price: $0.005 USDC
`GET /api/calc/hamilton_depression`
HTML: https://magentlab.com/docs/hamilton-depression
Markdown: https://magentlab.com/docs/hamilton-depression.md

Not a medical device. Not a diagnosis, dose, or listing recommendation.

## What it computes

Sum seventeen caller-assigned Hamilton 1960 items (eight integers 0-4 and nine integers 0-2) and return the published 0-50 total. Does not apply later total-score severity bands or the four excluded 21-item variables.

## When to use

When an agent already has Hamilton 1960 integers in the published per-item ranges and needs the published 17-variable total. magent does not interview the patient, diagnose depression, score the later 21-item form, or apply later 0-7/8-16/17-23/≥24 cutoffs.

## When not to use

- Not a medical device and not a depression diagnosis or treatment order.
- Each of the 17 variables is a caller-assigned integer in the Hamilton 1960 range for that item (0-4 five-point or 0-2 three-point). magent does not interview the patient.
- This is Hamilton 1960's 17 scored variables only (max 50). Items 18-21 on that form (diurnal variation, depersonalization, paranoid symptoms, obsessional symptoms) are excluded from the scale in that paper. magent does not score later 21-item HAM-D forms that rate agitation 0-4 (max 52).
- Hamilton 1960 published no total-score severity bands. This tool returns score and max_score only. It does not apply later 0-7/8-16/17-23/≥24 website or review cutoffs.
- Hamilton 1960 summed two raters (or doubled a single rater) for comparability. magent sums the 17 caller-assigned integers only and does not double the total.

## Formula

```
HAM-D = depressed_mood + guilt + suicide + insomnia_initial + insomnia_middle + insomnia_delayed + work_and_interests + retardation + agitation + anxiety_psychic + anxiety_somatic + somatic_gastrointestinal + somatic_general + genital_symptoms + hypochondriasis + insight + loss_of_weight; Hamilton 1960 17 variables (not items 18-21); 0-4 five-point for depressed_mood, guilt, suicide, work_and_interests, retardation, anxiety_psychic, anxiety_somatic, hypochondriasis; 0-2 three-point for insomnia_initial, insomnia_middle, insomnia_delayed, agitation, somatic_gastrointestinal, somatic_general, genital_symptoms, insight, loss_of_weight; max 50; no total-score severity bands
```

## Citation

[A rating scale for depression](https://doi.org/10.1136/jnnp.23.1.56)
Hamilton M
J Neurol Neurosurg Psychiatry. 1960;23(1):56-62
DOI: [10.1136/jnnp.23.1.56](https://doi.org/10.1136/jnnp.23.1.56)

## Worked example

### All items 0

Given: `agitation=0, anxiety_psychic=0, anxiety_somatic=0, depressed_mood=0, genital_symptoms=0, guilt=0, hypochondriasis=0, insight=0, insomnia_delayed=0, insomnia_initial=0, insomnia_middle=0, loss_of_weight=0, retardation=0, somatic_gastrointestinal=0, somatic_general=0, suicide=0, work_and_interests=0`

1. depressed_mood, guilt, suicide, insomnia_initial, insomnia_middle, insomnia_delayed, work_and_interests, retardation, agitation, anxiety_psychic, anxiety_somatic, somatic_gastrointestinal, somatic_general, genital_symptoms, hypochondriasis, insight, and loss_of_weight are 0 as assigned by the caller
2. Score = 0 (max 50). Hamilton 1960 published no total-score severity band.


### All items at published maximum

Given: `agitation=2, anxiety_psychic=4, anxiety_somatic=4, depressed_mood=4, genital_symptoms=2, guilt=4, hypochondriasis=4, insight=2, insomnia_delayed=2, insomnia_initial=2, insomnia_middle=2, loss_of_weight=2, retardation=4, somatic_gastrointestinal=2, somatic_general=2, suicide=4, work_and_interests=4`

1. eight Hamilton 1960 five-point items are 4 and nine three-point items (including agitation) are 2 as assigned by the caller
2. Score = 50 (max 50). No total-score severity band.


## Also searched as

- HAM-D
- HDRS
- HRSD
- Hamilton depression rating scale
- Hamilton Rating Scale for Depression
- HAM-D17
- Hamilton 1960 depression
- 17-item Hamilton depression

## Parameters

- `depressed_mood` (integer, required): Caller-assigned Hamilton 1960 depressed mood (integer 0-4: 0 absent, 1 mild or trivial, 2 moderate, 3 severe, 4 extreme): gloomy attitude, pessimism about the future, feeling of sadness, tendency to weep. magent does not interview the patient.
- `guilt` (integer, required): Caller-assigned Hamilton 1960 guilt (integer 0-4): self-reproach, ideas of guilt, present illness as punishment, delusions or hallucinations of guilt. magent does not interview the patient.
- `suicide` (integer, required): Caller-assigned Hamilton 1960 suicide (integer 0-4): feels life is not worth living, wishes to be dead, suicidal ideas; an attempt at suicide scores 4 (3 if sudden against little suicidal tendency). magent does not interview the patient.
- `insomnia_initial` (integer, required): Caller-assigned Hamilton 1960 insomnia, initial (integer 0-2: 0 absent, 1 slight or doubtful, 2 clearly present): difficulty in falling asleep. magent does not interview the patient.
- `insomnia_middle` (integer, required): Caller-assigned Hamilton 1960 insomnia, middle (integer 0-2): restless and disturbed during the night, waking during the night. magent does not interview the patient.
- `insomnia_delayed` (integer, required): Caller-assigned Hamilton 1960 insomnia, delayed (integer 0-2): waking in the early hours of the morning and unable to fall asleep again. magent does not interview the patient.
- `work_and_interests` (integer, required): Caller-assigned Hamilton 1960 work and interests (integer 0-4): feelings of incapacity, listlessness, loss of interest in hobbies, decreased social activities or productivity; given up work solely because of present illness is 4. magent does not interview the patient.
- `retardation` (integer, required): Caller-assigned Hamilton 1960 retardation (integer 0-4): slowness of thought, speech, and activity, apathy, stupor (1 slight at interview, 2 obvious, 3 interview difficult, 4 complete stupor). magent does not interview the patient.
- `agitation` (integer, required): Caller-assigned Hamilton 1960 agitation (integer 0-2 three-point; a five-point scale was impracticable in that paper): restlessness associated with anxiety. magent does not interview the patient.
- `anxiety_psychic` (integer, required): Caller-assigned Hamilton 1960 anxiety, psychic (integer 0-4): tension and irritability, worrying about minor matters, apprehensive attitude, fears. magent does not interview the patient.
- `anxiety_somatic` (integer, required): Caller-assigned Hamilton 1960 anxiety, somatic (integer 0-4): gastrointestinal (wind, indigestion), cardiovascular (palpitations, headaches), respiratory, genito-urinary, and other somatic anxiety. magent does not interview the patient.
- `somatic_gastrointestinal` (integer, required): Caller-assigned Hamilton 1960 somatic symptoms, gastrointestinal (integer 0-2): loss of appetite, heavy feelings in abdomen, constipation. magent does not interview the patient.
- `somatic_general` (integer, required): Caller-assigned Hamilton 1960 somatic symptoms, general (integer 0-2): heaviness in limbs, back, or head; diffuse backache; loss of energy and fatiguability. magent does not interview the patient.
- `genital_symptoms` (integer, required): Caller-assigned Hamilton 1960 genital symptoms (integer 0-2): loss of libido, menstrual disturbances. magent does not interview the patient.
- `hypochondriasis` (integer, required): Caller-assigned Hamilton 1960 hypochondriasis (integer 0-4): self-absorption (bodily), preoccupation with health, querulous attitude, hypochondriacal delusions. magent does not interview the patient.
- `insight` (integer, required): Caller-assigned Hamilton 1960 insight (integer 0-2: 0 no loss, 1 partial or doubtful loss, 2 loss of insight), interpreted in terms of the patient's understanding and background. magent does not interview the patient.
- `loss_of_weight` (integer, required): Caller-assigned Hamilton 1960 loss of weight (integer 0-2 three-point scale as published, because few patients know their normal weight). magent does not weigh the patient.

## Bulk (POST)

POST the same path with a JSON items array. The first item is the GET unit; each additional item is $0.002. Invalid items return HTTP 400 before settlement.

Method: `POST /api/calc/hamilton_depression`
Max items: 25
Price: unit_amount + extra_item_amount * (n - 1) (unit 5000 atomic, extra 2000 atomic)
Status: PREVIEW

- 1 to 25 items. Each item uses the same keys as the GET query parameters.
- POST of 1 item costs the same as GET. Lists longer than 25: chunk into multiple POSTs. Extra items still execute; do not pad dummy rows.
- The first invalid item fails the whole request (index in the 400 JSON). You are not charged.
- HTTP 200 is {count, path, items}. Each items[i] is the GET 200 body for that row.
- Catalog misses (empty matches, found=false) stay paid 200s inside that slot.
- x402 resource URL is this path plus n and body_sha256. Browsers that prefer text/html get the same paywall as GET; Pay retries POST with the same items.

Example request:

```json
{
  "items": [
    {
      "agitation": "0",
      "anxiety_psychic": "0",
      "anxiety_somatic": "0",
      "depressed_mood": "0",
      "genital_symptoms": "0",
      "guilt": "0",
      "hypochondriasis": "0",
      "insight": "0",
      "insomnia_delayed": "0",
      "insomnia_initial": "0",
      "insomnia_middle": "0",
      "loss_of_weight": "0",
      "retardation": "0",
      "somatic_gastrointestinal": "0",
      "somatic_general": "0",
      "suicide": "0",
      "work_and_interests": "0"
    },
    {
      "agitation": "0",
      "anxiety_psychic": "0",
      "anxiety_somatic": "0",
      "depressed_mood": "0",
      "genital_symptoms": "0",
      "guilt": "0",
      "hypochondriasis": "0",
      "insight": "0",
      "insomnia_delayed": "0",
      "insomnia_initial": "0",
      "insomnia_middle": "0",
      "loss_of_weight": "0",
      "retardation": "0",
      "somatic_gastrointestinal": "0",
      "somatic_general": "0",
      "suicide": "0",
      "work_and_interests": "0"
    }
  ]
}
```

Human paywall (two-item fixture): https://api.magentlab.com/paywall/bulk/hamilton-depression

Example 200:

```json
{
  "count": 2,
  "path": "/api/calc/hamilton_depression",
  "items": [
    {
      "components": [
        {
          "value": 0,
          "factor": "depressed_mood",
          "points": 0,
          "present": true
        },
        {
          "value": 0,
          "factor": "guilt",
          "points": 0,
          "present": true
        },
        {
          "value": 0,
          "factor": "suicide",
          "points": 0,
          "present": true
        },
        {
          "value": 0,
          "factor": "insomnia_initial",
          "points": 0,
          "present": true
        },
        {
          "value": 0,
          "factor": "insomnia_middle",
          "points": 0,
          "present": true
        },
        {
          "value": 0,
          "factor": "insomnia_delayed",
          "points": 0,
          "present": true
        },
        {
          "value": 0,
          "factor": "work_and_interests",
          "points": 0,
          "present": true
        },
        {
          "value": 0,
          "factor": "retardation",
          "points": 0,
          "present": true
        },
        {
          "value": 0,
          "factor": "agitation",
          "points": 0,
          "present": true
        },
        {
          "value": 0,
          "factor": "anxiety_psychic",
          "points": 0,
          "present": true
        },
        {
          "value": 0,
          "factor": "anxiety_somatic",
          "points": 0,
          "present": true
        },
        {
          "value": 0,
          "factor": "somatic_gastrointestinal",
          "points": 0,
          "present": true
        },
        {
          "value": 0,
          "factor": "somatic_general",
          "points": 0,
          "present": true
        },
        {
          "value": 0,
          "factor": "genital_symptoms",
          "points": 0,
          "present": true
        },
        {
          "value": 0,
          "factor": "hypochondriasis",
          "points": 0,
          "present": true
        },
        {
          "value": 0,
          "factor": "insight",
          "points": 0,
          "present": true
        },
        {
          "value": 0,
          "factor": "loss_of_weight",
          "points": 0,
          "present": true
        }
      ],
      "disclaimer": "Not a medical device. Deterministic published-formula or published-code output for autonomous agents. A licensed clinician remains responsible for patient care and billing submissions.",
      "citation": {
        "authors": "Hamilton M",
        "doi": "10.1136/jnnp.23.1.56",
        "id": "hamilton-1960",
        "pmid": "14399272",
        "source": "J Neurol Neurosurg Psychiatry. 1960;23(1):56-62",
        "title": "A rating scale for depression"
      },
      "formula": "hamilton_depression",
      "formula_expression": "HAM-D = depressed_mood + guilt + suicide + insomnia_initial + insomnia_middle + insomnia_delayed + work_and_interests + retardation + agitation + anxiety_psychic + anxiety_somatic + somatic_gastrointestinal + somatic_general + genital_symptoms + hypochondriasis + insight + loss_of_weight; Hamilton 1960 17 variables (not items 18-21); 0-4 five-point for depressed_mood, guilt, suicide, work_and_interests, retardation, anxiety_psychic, anxiety_somatic, hypochondriasis; 0-2 three-point for insomnia_initial, insomnia_middle, insomnia_delayed, agitation, somatic_gastrointestinal, somatic_general, genital_symptoms, insight, loss_of_weight; max 50; no total-score severity bands",
      "max_score": 50,
      "score": 0
    },
    {
      "components": [
        {
          "value": 0,
          "factor": "depressed_mood",
          "points": 0,
          "present": true
        },
        {
          "value": 0,
          "factor": "guilt",
          "points": 0,
          "present": true
        },
        {
          "value": 0,
          "factor": "suicide",
          "points": 0,
          "present": true
        },
        {
          "value": 0,
          "factor": "insomnia_initial",
          "points": 0,
          "present": true
        },
        {
          "value": 0,
          "factor": "insomnia_middle",
          "points": 0,
          "present": true
        },
        {
          "value": 0,
          "factor": "insomnia_delayed",
          "points": 0,
          "present": true
        },
        {
          "value": 0,
          "factor": "work_and_interests",
          "points": 0,
          "present": true
        },
        {
          "value": 0,
          "factor": "retardation",
          "points": 0,
          "present": true
        },
        {
          "value": 0,
          "factor": "agitation",
          "points": 0,
          "present": true
        },
        {
          "value": 0,
          "factor": "anxiety_psychic",
          "points": 0,
          "present": true
        },
        {
          "value": 0,
          "factor": "anxiety_somatic",
          "points": 0,
          "present": true
        },
        {
          "value": 0,
          "factor": "somatic_gastrointestinal",
          "points": 0,
          "present": true
        },
        {
          "value": 0,
          "factor": "somatic_general",
          "points": 0,
          "present": true
        },
        {
          "value": 0,
          "factor": "genital_symptoms",
          "points": 0,
          "present": true
        },
        {
          "value": 0,
          "factor": "hypochondriasis",
          "points": 0,
          "present": true
        },
        {
          "value": 0,
          "factor": "insight",
          "points": 0,
          "present": true
        },
        {
          "value": 0,
          "factor": "loss_of_weight",
          "points": 0,
          "present": true
        }
      ],
      "disclaimer": "Not a medical device. Deterministic published-formula or published-code output for autonomous agents. A licensed clinician remains responsible for patient care and billing submissions.",
      "citation": {
        "authors": "Hamilton M",
        "doi": "10.1136/jnnp.23.1.56",
        "id": "hamilton-1960",
        "pmid": "14399272",
        "source": "J Neurol Neurosurg Psychiatry. 1960;23(1):56-62",
        "title": "A rating scale for depression"
      },
      "formula": "hamilton_depression",
      "formula_expression": "HAM-D = depressed_mood + guilt + suicide + insomnia_initial + insomnia_middle + insomnia_delayed + work_and_interests + retardation + agitation + anxiety_psychic + anxiety_somatic + somatic_gastrointestinal + somatic_general + genital_symptoms + hypochondriasis + insight + loss_of_weight; Hamilton 1960 17 variables (not items 18-21); 0-4 five-point for depressed_mood, guilt, suicide, work_and_interests, retardation, anxiety_psychic, anxiety_somatic, hypochondriasis; 0-2 three-point for insomnia_initial, insomnia_middle, insomnia_delayed, agitation, somatic_gastrointestinal, somatic_general, genital_symptoms, insight, loss_of_weight; max 50; no total-score severity bands",
      "max_score": 50,
      "score": 0
    }
  ]
}
```

## Response fields

- `formula` (string): hamilton_depression
- `formula_expression` (string): Exact expression used
- `score` (integer): Hamilton 1960 sum of 17 caller-assigned items (eight 0-4 and nine 0-2; total 0-50)
- `max_score` (integer): Always 50
- `components` (array): Per-item caller-assigned points
- `citation` (object): Hamilton J Neurol Neurosurg Psychiatry 1960 citation
- `disclaimer` (string): Not-a-device notice

## Example JSON

Frozen fixture. Not a live lookup.

```json
{
  "components": [
    {
      "value": 0,
      "factor": "depressed_mood",
      "points": 0,
      "present": true
    },
    {
      "value": 0,
      "factor": "guilt",
      "points": 0,
      "present": true
    },
    {
      "value": 0,
      "factor": "suicide",
      "points": 0,
      "present": true
    },
    {
      "value": 0,
      "factor": "insomnia_initial",
      "points": 0,
      "present": true
    },
    {
      "value": 0,
      "factor": "insomnia_middle",
      "points": 0,
      "present": true
    },
    {
      "value": 0,
      "factor": "insomnia_delayed",
      "points": 0,
      "present": true
    },
    {
      "value": 0,
      "factor": "work_and_interests",
      "points": 0,
      "present": true
    },
    {
      "value": 0,
      "factor": "retardation",
      "points": 0,
      "present": true
    },
    {
      "value": 0,
      "factor": "agitation",
      "points": 0,
      "present": true
    },
    {
      "value": 0,
      "factor": "anxiety_psychic",
      "points": 0,
      "present": true
    },
    {
      "value": 0,
      "factor": "anxiety_somatic",
      "points": 0,
      "present": true
    },
    {
      "value": 0,
      "factor": "somatic_gastrointestinal",
      "points": 0,
      "present": true
    },
    {
      "value": 0,
      "factor": "somatic_general",
      "points": 0,
      "present": true
    },
    {
      "value": 0,
      "factor": "genital_symptoms",
      "points": 0,
      "present": true
    },
    {
      "value": 0,
      "factor": "hypochondriasis",
      "points": 0,
      "present": true
    },
    {
      "value": 0,
      "factor": "insight",
      "points": 0,
      "present": true
    },
    {
      "value": 0,
      "factor": "loss_of_weight",
      "points": 0,
      "present": true
    }
  ],
  "disclaimer": "Not a medical device. Deterministic published-formula or published-code output for autonomous agents. A licensed clinician remains responsible for patient care and billing submissions.",
  "citation": {
    "authors": "Hamilton M",
    "doi": "10.1136/jnnp.23.1.56",
    "id": "hamilton-1960",
    "pmid": "14399272",
    "source": "J Neurol Neurosurg Psychiatry. 1960;23(1):56-62",
    "title": "A rating scale for depression"
  },
  "formula": "hamilton_depression",
  "formula_expression": "HAM-D = depressed_mood + guilt + suicide + insomnia_initial + insomnia_middle + insomnia_delayed + work_and_interests + retardation + agitation + anxiety_psychic + anxiety_somatic + somatic_gastrointestinal + somatic_general + genital_symptoms + hypochondriasis + insight + loss_of_weight; Hamilton 1960 17 variables (not items 18-21); 0-4 five-point for depressed_mood, guilt, suicide, work_and_interests, retardation, anxiety_psychic, anxiety_somatic, hypochondriasis; 0-2 three-point for insomnia_initial, insomnia_middle, insomnia_delayed, agitation, somatic_gastrointestinal, somatic_general, genital_symptoms, insight, loss_of_weight; max 50; no total-score severity bands",
  "max_score": 50,
  "score": 0
}
```

## Errors

- HTTP 400 `invalid_hamilton_depression`: Hamilton depression rating items must be integers in the Hamilton 1960 published ranges for those 17 variables. Returned before settlement; you are not charged.
- HTTP 400 `invalid_items`: POST body must be a JSON object with only an items array Returned before settlement; you are not charged.
- HTTP 400 `invalid_item_count`: items must be an array of 1 to 25 objects Returned before settlement; you are not charged.
- HTTP 400 `invalid_item`: each items entry must be a JSON object Returned before settlement; you are not charged.

Shared HTTP 402 and 503: https://magentlab.com/docs/payments

## Related tools

- [PHQ-9](https://magentlab.com/docs/phq-9) — Sum nine caller-assigned Kroenke 2001 PHQ-9 integers (0-3) and return the published total (max 27), severity cutpoints, and ≥10 screen.
- [QIDS](https://magentlab.com/docs/qids) — Map 16 caller-assigned Rush 2003 QIDS-SR integers (0-3) to nine DSM-IV domains (sleep, appetite/weight, and psychomotor are each the published max of their items) and return the 0-27 total and IRT severity band.
- [MDI](https://magentlab.com/docs/mdi) — Map 12 caller-assigned Bech 2001 MDI integers (0-5 over the last 2 weeks) to ten DSM-IV/ICD-10 symptom items (appetite and psychomotor are each the published max of their pair) and return the 0-50 total and whether it meets this paper's optimal cutoff of 26.

## Payment

Unpaid requests return HTTP 402 even if query parameters or POST items are missing or invalid, so CDP and agents can index the path. After a PAYMENT-SIGNATURE, invalid params return HTTP 400 JSON before settlement. magent does not charge. Fix the params, then request a new 402 quote for that complete URL. Catalog misses (empty matches, found=false) are valid paid 200s.

- GET the tool with Accept: application/json (do not send Accept: text/html unless you want the human paywall).
- HTTP 402 means you have not paid. Decode the base64 PAYMENT-REQUIRED header. HTTP 503 is not a new quote.
- Sign accepts[0] (exact, EIP-3009) with validBefore = now + maxTimeoutSeconds (600 seconds), or accepts[1] (batch-settlement deposit/voucher) on product GET. Ping and POST {items} stay exact. Magent retries transient facilitator 429/5xx before answering.
- Retry the same URL with PAYMENT-SIGNATURE (base64 JSON of accepted and payload). Magent attaches canonical extensions.bazaar on CDP verify/settle; echoing 402 bazaar is optional.
- Success is HTTP 200 JSON plus PAYMENT-RESPONSE. exact settles before the tool. batch-settlement verifies (and deposit-settles) before the tool and commits the charge after HTTP 2xx. HTTP 503: retry the same PAYMENT-SIGNATURE. Mint a new exact nonce only after a new HTTP 402.

- offered `exact` on eip155:8453: Fixed-price USDC on Base. The buyer authorizes the advertised amount (EIP-3009). magent settles before the tool runs (paymentFlow upfront). extra.assetTransferMethod=eip3009 extra.paymentFlow=upfront.
- offered `batch-settlement` on eip155:8453: Payment-channel vouchers claimed later in batches. Exact stays accepts[0]. Same-path POST {items} is still exact. extra.assetTransferMethod=eip3009 extra.paymentFlow=authorization.

- not offered `upto`: Not offered. Usage-based: buyer authorizes a ceiling, seller settles the actual amount after work. Reserved for a future metered tool. Not for current calculators or code search.

Same-path POST {items} is still scheme exact: one EIP-3009 authorization for GET unit plus $0.002 per extra item. That is not x402 batch-settlement (payment channels / vouchers).

Shared HTTP 402 and 503 table: https://magentlab.com/docs/payments

Stdio MCP (one process per host): https://magentlab.com/docs/mcp

## Guarantees

- HTTP 402 is unpaid, including a missing query. After PAYMENT-SIGNATURE, invalid parameters return HTTP 400 before settlement. You are not charged. HTTP 402 never includes the tool JSON.
- exact: settlement finishes before the tool (paymentFlow upfront). batch-settlement: verify/deposit before the tool; chargedCumulativeAmount commits after HTTP 2xx. Uncertain or failed settlement fails closed (HTTP 503). Retry the same PAYMENT-SIGNATURE.
- HTTP 402 is unpaid only. Do not sign a second authorization because of a 503.
- Execution is timeout-bounded and concurrency-capped.
- Calculator inputs are stored encrypted for allowlisted operators (Magent Console). They are not in public logs, SSH lookups, catalog, or rollups. Request logs store path without query.