---
title: "Full score-history record of one coin (paid, $0.05, x402 or MPP; included with the Premium agent key; sold only beyond the free slice)"
method: POST
path: "/premium/score-history"
tags: ["Paid (x402 or MPP)"]
---

# Full score-history record of one coin (paid, $0.05, x402 or MPP; included with the Premium agent key; sold only beyond the free slice)

`POST /premium/score-history`

## Request

- Base URL: `https://truevaluerankings.com`
- URL: `https://truevaluerankings.com/premium/score-history`
- Auth: one of:
  - none
  - HTTP bearer

Score history: every recorded change to a coin's eight metric scores as a dated record with the TVR Score, the scoring method version, a source label (baseline for the opening record, auto_captured for rows written from the change itself), the public reason where one was recorded, and a SHA-256 hash of the record. Forward-only from the day the record began; nothing is reconstructed and no reason is invented. Free slice (the last 90 days or the last 3 records, whichever is longer) at GET https://truevaluerankings.com/api/history/{symbol} and in the MCP tool get_historical_scores. The full record is included with the Premium agent key (scope "full") and is sold per pull ($0.05, x402 or MPP, POST https://truevaluerankings.com/premium/score-history) only once a coin's record extends beyond the free slice; until then the request is refused before any payment and the free slice is the whole record. Flow: POST {"coin": "BTC"} without payment returns 402 with the challenge headers when the record is sellable; pay exactly 50000 units (USDC on Base through x402, or USDC.e on Tempo through MPP) and retry the same request with the payment header; the response is 200 with the full record and a receipt header. When the coin's record has nothing beyond the free slice the request is refused with 400 (reason nothing_beyond_free_slice) before any payment, and the free slice at GET /api/history/{symbol} is the whole record. Premium subscribers send their agent key as Authorization: Bearer tvr_k_... instead of a payment. A lost response is re-delivered on the same proof for 24 hours without a second charge. MCP tool: get_historical_scores with scope "full".

## Headers

- `PAYMENT-SIGNATURE` string
- `Authorization` string

## Request body

- object
  - `coin` string, required: Ticker or name of a covered coin

## Response `200`

Paid and delivered (or included with the agent key). The full record: every dated score state with the TVR Score, method version, source label, public reason where recorded, and record hash.

- object
  - `success` boolean
  - `product` string
  - `symbol` string
  - `period` object
  - `coverage` object
  - `method_versions` object[]
  - `records` object[]
    - `as_of` string, date
    - `revision` integer
    - `source` 'baseline' | 'auto_captured' | 'manual'
    - `scores` object
    - `tvr_score` number, nullable
    - `method_version` string
    - `changed_metrics` string[]
    - `reason_public` string, nullable
    - `published_at` string, date-time
    - `record_hash` string: SHA-256, hex
  - `hash_format` string
  - `payment` object
  - `legal` object

## Other responses

- `400`: Invalid input (unknown coin), or nothing beyond the free slice for this coin yet (reason nothing_beyond_free_slice). Refused before any payment; no challenge is issued.
- `401`: An agent key was presented but is unknown or revoked. Nothing charged.
- `402`: Payment required or payment not accepted. The PAYMENT-REQUIRED header carries the x402 challenge and WWW-Authenticate the MPP challenge; the body explains how to pay. Nothing has been charged.
- `403`: An agent key was presented but its account has no active Premium subscription. Nothing charged; pay per call or subscribe.
- `405`: Method not allowed. Use POST with a JSON body (OPTIONS is answered with 204).
- `409`: The presented proof was already used for a different input. One purchase unlocks one intended result.
- `410`: The stored result for this proof has expired (24 hours); pay again for a fresh result.
- `429`: Rate limit, or the presented agent key has used its daily cap or the account its monthly allowance. Nothing charged; TVR never switches to a wallet payment on its own.
- `503`: Settlement status unknown or the engine is unavailable; nothing was charged. Retry shortly.

---

[API](https://skmtc.dev/truevaluerankings/apis/true-value-rankings-api.md) · [All operations](https://skmtc.dev/truevaluerankings/apis/true-value-rankings-api/llms.txt) · [OpenAPI document](https://skmtc.dev/truevaluerankings/apis/true-value-rankings-api/revisions/c2cb1728b93c?raw)