# HIRI-MSM HIV incidence risk index HIRI-MSM Status: LIVE Price: $0.005 USDC `GET /api/calc/hiri_msm` HTML: https://magentlab.com/docs/hiri-msm Markdown: https://magentlab.com/docs/hiri-msm.md Not a medical device. Not a diagnosis, dose, or listing recommendation. ## What it computes Sum the published Smith 2012 seven-item HIV incidence risk index for MSM (age plus six prior-6-month behaviors, 0–47) and return at_or_above_10 when the total is ≥10. ## When to use When an agent needs the published Smith 2012 point total from caller-assigned counts and must not invent a diagnosis, a PrEP order, or a sexual history. ## When not to use - Not a medical device. Not a diagnosis of HIV infection and not a PrEP, nPEP, or antiretroviral order. - Smith 2012 seven-item index only (age + six 6-month behaviors). Range 0–47. Published screening cutoff score ≥10. Not Menza 2009 and not the SexPro model. - Counts and flags are caller-assigned. magent does not take a sexual history or a substance-use history. No race field. - Keeps the HIV-positive partner count. Not a simplified 6-input website variant that drops that item or changes the published bands. - Age is 18–120. The paper listed <18 as 0 points; magent rejects age outside 18–120 as invalid_age. ## Formula ``` HIRI-MSM = age + male_sex_partners_6mo + hiv_positive_male_partners_6mo + unprotected_receptive_anal_6mo + insertive_anal_hiv_positive_6mo + poppers_6mo + amphetamines_6mo; age 18-28 -> 8, 29-40 -> 5, 41-48 -> 2, >=49 -> 0; male partners 0-5 -> 0, 6-10 -> 4, >=11 -> 7; HIV-positive partners 0 -> 0, 1 -> 4, >=2 -> 8; unprotected receptive anal 0 -> 0, >=1 -> 10; insertive anal with HIV-positive partner 0-4 -> 0, >=5 -> 6; poppers true -> 3; amphetamines true -> 5; max 47; at_or_above_10 iff score>=10 ``` ## Citation [Development of a Clinical Screening Index Predictive of Incident HIV Infection Among Men Who Have Sex With Men in the United States](https://doi.org/10.1097/QAI.0b013e318256b2f6) Smith DK, Pals SL, Herbst JH, Shinde S, Carey JW J Acquir Immune Defic Syndr. 2012;60(4):421-427 DOI: [10.1097/QAI.0b013e318256b2f6](https://doi.org/10.1097/QAI.0b013e318256b2f6) ## Worked example ### Lowest-risk row (older age, zero partners/acts, no poppers/amphetamines) Given: `age=55, amphetamines_6mo=false, hiv_positive_male_partners_6mo=0, insertive_anal_hiv_positive_6mo=0, male_sex_partners_6mo=0, poppers_6mo=false, unprotected_receptive_anal_6mo=0` 1. Age 55 ≥49 → 0; male partners 0 → 0; HIV-positive partners 0 → 0 2. Unprotected receptive anal 0 → 0; insertive anal with HIV-positive partner 0 → 0; poppers false → 0; amphetamines false → 0 3. Score = 0 (published max 47); at_or_above_10 false (cutoff ≥10) ### Cutoff ≥10 (one unprotected receptive anal act) Given: `age=55, amphetamines_6mo=false, hiv_positive_male_partners_6mo=0, insertive_anal_hiv_positive_6mo=0, male_sex_partners_6mo=0, poppers_6mo=false, unprotected_receptive_anal_6mo=1` 1. Age 55 → 0; unprotected receptive anal ≥1 → 10; other items 0 2. Score = 10; at_or_above_10 true (cutoff ≥10). Not a diagnosis or PrEP order. ## Also searched as - HIRI-MSM - HIV incidence risk index - Smith 2012 HIV risk index - MSM HIV screening index - HIV risk index for MSM - seven-item MSM HIV index ## Parameters - `age` (integer, required): Age in years (18-120). Smith 2012: 18-28 scores 8; 29-40 scores 5; 41-48 scores 2; ≥49 scores 0. Caller-assigned. magent does not take a sexual history. - `male_sex_partners_6mo` (integer, required): Caller-assigned number of male sex partners in the prior 6 months (0-500). Smith 2012: 0-5 scores 0; 6-10 scores 4; ≥11 scores 7. - `hiv_positive_male_partners_6mo` (integer, required): Caller-assigned number of HIV-positive male sex partners in the prior 6 months (0-500). Smith 2012: 0 scores 0; 1 scores 4; ≥2 scores 8. Do not drop this item. - `unprotected_receptive_anal_6mo` (integer, required): Caller-assigned times the person had unprotected receptive anal sex with a male partner of any HIV status in the prior 6 months (0-500). Smith 2012: 0 scores 0; ≥1 scores 10. - `insertive_anal_hiv_positive_6mo` (integer, required): Caller-assigned times the person had insertive anal sex with an HIV-positive male partner in the prior 6 months (0-500). Smith 2012: 0-4 scores 0; ≥5 scores 6. - `poppers_6mo` (boolean, required): Caller-assigned popper (amyl nitrate) use in the prior 6 months (Smith 2012). true or false. magent does not take a substance-use history. - `amphetamines_6mo` (boolean, required): Caller-assigned amphetamine use in the prior 6 months (Smith 2012). true or false. magent does not take a substance-use history. ## 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/hiri_msm` 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": [ { "age": "55", "amphetamines_6mo": "false", "hiv_positive_male_partners_6mo": "0", "insertive_anal_hiv_positive_6mo": "0", "male_sex_partners_6mo": "0", "poppers_6mo": "false", "unprotected_receptive_anal_6mo": "0" }, { "age": "55", "amphetamines_6mo": "false", "hiv_positive_male_partners_6mo": "0", "insertive_anal_hiv_positive_6mo": "0", "male_sex_partners_6mo": "0", "poppers_6mo": "false", "unprotected_receptive_anal_6mo": "0" } ] } ``` Human paywall (two-item fixture): https://api.magentlab.com/paywall/bulk/hiri-msm Example 200: ```json { "count": 2, "path": "/api/calc/hiri_msm", "items": [ { "components": [ { "value": 55, "factor": "age", "points": 0, "present": false }, { "value": 0, "factor": "male_sex_partners_6mo", "points": 0, "present": false }, { "value": 0, "factor": "hiv_positive_male_partners_6mo", "points": 0, "present": false }, { "value": 0, "factor": "unprotected_receptive_anal_6mo", "points": 0, "present": false }, { "value": 0, "factor": "insertive_anal_hiv_positive_6mo", "points": 0, "present": false }, { "factor": "poppers_6mo", "points": 0, "present": false }, { "factor": "amphetamines_6mo", "points": 0, "present": false } ], "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": "Smith DK, Pals SL, Herbst JH, Shinde S, Carey JW", "doi": "10.1097/QAI.0b013e318256b2f6", "id": "smith-dk-2012", "pmid": "22487585", "source": "J Acquir Immune Defic Syndr. 2012;60(4):421-427", "title": "Development of a Clinical Screening Index Predictive of Incident HIV Infection Among Men Who Have Sex With Men in the United States" }, "formula": "hiri_msm", "formula_expression": "HIRI-MSM = age + male_sex_partners_6mo + hiv_positive_male_partners_6mo + unprotected_receptive_anal_6mo + insertive_anal_hiv_positive_6mo + poppers_6mo + amphetamines_6mo; age 18-28 -> 8, 29-40 -> 5, 41-48 -> 2, >=49 -> 0; male partners 0-5 -> 0, 6-10 -> 4, >=11 -> 7; HIV-positive partners 0 -> 0, 1 -> 4, >=2 -> 8; unprotected receptive anal 0 -> 0, >=1 -> 10; insertive anal with HIV-positive partner 0-4 -> 0, >=5 -> 6; poppers true -> 3; amphetamines true -> 5; max 47; at_or_above_10 iff score>=10", "age_years": 55, "max_score": 47, "score": 0, "at_or_above_10": false, "hiv_positive_male_partners_6mo": 0, "insertive_anal_hiv_positive_6mo": 0, "male_sex_partners_6mo": 0, "unprotected_receptive_anal_6mo": 0 }, { "components": [ { "value": 55, "factor": "age", "points": 0, "present": false }, { "value": 0, "factor": "male_sex_partners_6mo", "points": 0, "present": false }, { "value": 0, "factor": "hiv_positive_male_partners_6mo", "points": 0, "present": false }, { "value": 0, "factor": "unprotected_receptive_anal_6mo", "points": 0, "present": false }, { "value": 0, "factor": "insertive_anal_hiv_positive_6mo", "points": 0, "present": false }, { "factor": "poppers_6mo", "points": 0, "present": false }, { "factor": "amphetamines_6mo", "points": 0, "present": false } ], "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": "Smith DK, Pals SL, Herbst JH, Shinde S, Carey JW", "doi": "10.1097/QAI.0b013e318256b2f6", "id": "smith-dk-2012", "pmid": "22487585", "source": "J Acquir Immune Defic Syndr. 2012;60(4):421-427", "title": "Development of a Clinical Screening Index Predictive of Incident HIV Infection Among Men Who Have Sex With Men in the United States" }, "formula": "hiri_msm", "formula_expression": "HIRI-MSM = age + male_sex_partners_6mo + hiv_positive_male_partners_6mo + unprotected_receptive_anal_6mo + insertive_anal_hiv_positive_6mo + poppers_6mo + amphetamines_6mo; age 18-28 -> 8, 29-40 -> 5, 41-48 -> 2, >=49 -> 0; male partners 0-5 -> 0, 6-10 -> 4, >=11 -> 7; HIV-positive partners 0 -> 0, 1 -> 4, >=2 -> 8; unprotected receptive anal 0 -> 0, >=1 -> 10; insertive anal with HIV-positive partner 0-4 -> 0, >=5 -> 6; poppers true -> 3; amphetamines true -> 5; max 47; at_or_above_10 iff score>=10", "age_years": 55, "max_score": 47, "score": 0, "at_or_above_10": false, "hiv_positive_male_partners_6mo": 0, "insertive_anal_hiv_positive_6mo": 0, "male_sex_partners_6mo": 0, "unprotected_receptive_anal_6mo": 0 } ] } ``` ## Response fields - `formula` (string): hiri_msm - `formula_expression` (string): Exact expression used - `score` (integer): Smith 2012 HIRI-MSM points 0-47 - `max_score` (integer): 47 - `at_or_above_10` (boolean): true when score ≥10, the published Smith 2012 screening cutoff. Not a diagnosis or PrEP order. - `age_years` (integer): Age in years used for the age band - `male_sex_partners_6mo` (integer): Caller-assigned male sex partners in the prior 6 months - `hiv_positive_male_partners_6mo` (integer): Caller-assigned HIV-positive male partners in the prior 6 months - `unprotected_receptive_anal_6mo` (integer): Caller-assigned unprotected receptive anal acts in the prior 6 months - `insertive_anal_hiv_positive_6mo` (integer): Caller-assigned insertive anal acts with an HIV-positive partner in the prior 6 months - `components` (array): Per-item points - `citation` (object): Smith et al. JAIDS 2012 citation - `disclaimer` (string): Not-a-device notice ## Example JSON Frozen fixture. Not a live lookup. ```json { "components": [ { "value": 55, "factor": "age", "points": 0, "present": false }, { "value": 0, "factor": "male_sex_partners_6mo", "points": 0, "present": false }, { "value": 0, "factor": "hiv_positive_male_partners_6mo", "points": 0, "present": false }, { "value": 0, "factor": "unprotected_receptive_anal_6mo", "points": 0, "present": false }, { "value": 0, "factor": "insertive_anal_hiv_positive_6mo", "points": 0, "present": false }, { "factor": "poppers_6mo", "points": 0, "present": false }, { "factor": "amphetamines_6mo", "points": 0, "present": false } ], "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": "Smith DK, Pals SL, Herbst JH, Shinde S, Carey JW", "doi": "10.1097/QAI.0b013e318256b2f6", "id": "smith-dk-2012", "pmid": "22487585", "source": "J Acquir Immune Defic Syndr. 2012;60(4):421-427", "title": "Development of a Clinical Screening Index Predictive of Incident HIV Infection Among Men Who Have Sex With Men in the United States" }, "formula": "hiri_msm", "formula_expression": "HIRI-MSM = age + male_sex_partners_6mo + hiv_positive_male_partners_6mo + unprotected_receptive_anal_6mo + insertive_anal_hiv_positive_6mo + poppers_6mo + amphetamines_6mo; age 18-28 -> 8, 29-40 -> 5, 41-48 -> 2, >=49 -> 0; male partners 0-5 -> 0, 6-10 -> 4, >=11 -> 7; HIV-positive partners 0 -> 0, 1 -> 4, >=2 -> 8; unprotected receptive anal 0 -> 0, >=1 -> 10; insertive anal with HIV-positive partner 0-4 -> 0, >=5 -> 6; poppers true -> 3; amphetamines true -> 5; max 47; at_or_above_10 iff score>=10", "age_years": 55, "max_score": 47, "score": 0, "at_or_above_10": false, "hiv_positive_male_partners_6mo": 0, "insertive_anal_hiv_positive_6mo": 0, "male_sex_partners_6mo": 0, "unprotected_receptive_anal_6mo": 0 } ``` ## Errors - HTTP 400 `invalid_age`: age must be an integer from 18 to 120 Returned before settlement; you are not charged. - HTTP 400 `invalid_sex_partner_count`: male_sex_partners_6mo must be an integer from 0 to 500 (Smith 2012 HIRI-MSM male partners in the prior 6 months). Returned before settlement; you are not charged. - HTTP 400 `invalid_anal_act_count`: unprotected_receptive_anal_6mo and insertive_anal_hiv_positive_6mo must each be an integer from 0 to 500 (Smith 2012 HIRI-MSM act counts in the prior 6 months). Returned before settlement; you are not charged. - HTTP 400 `invalid_flag`: boolean clinical flags must be true or false 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 - [Menza](https://magentlab.com/docs/menza) — Sum the four Menza 2009 caller-assigned flags and return the 0–19 point total. - [CAGE](https://magentlab.com/docs/cage) — Sum the four Ewing 1984 CAGE items and return whether two or more answers are affirmative. ## 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.