---
title: "Custom-weight rerank of every covered coin (paid, $0.05, x402 or MPP)"
method: POST
path: "/premium/custom-ranking"
tags: ["Paid (x402 or MPP)"]
---

# Custom-weight rerank of every covered coin (paid, $0.05, x402 or MPP)

`POST /premium/custom-ranking`

## Request

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

Custom-weight rerank of every cryptocurrency covered by True Value Rankings: the full TVR table recomputed with the caller's own weights for the 8 fundamental metrics, using TVR's non-public score transformation. $0.05 per call, paid in-band with x402 (USDC on Base) or MPP (USDC.e on Tempo, tempo charge, push mode). Educational model output, not a recommendation. Flow: POST without payment returns 402 with the challenge headers; pay exactly 50000 units (USDC on Base through x402, EIP-3009 authorization signed for the payTo address, or USDC.e on Tempo through MPP, push mode) and retry the same request with the payment header; the response is 200 with the ranking and a receipt header. Invalid input is refused with 400 before any payment. A lost response is re-delivered on the same proof for 24 hours without a second charge; the same proof with different inputs is refused with 409. The live x402 offer, field for field, is at https://truevaluerankings.com/.well-known/x402.json. Free alternative: the four built-in presets through POST /api/calculate-batch. MCP tool: get_custom_ranking. A GET on this path returns the same x402 challenge (PAYMENT-REQUIRED header) as a quote, never a sale, and carries no MPP challenge; a POST with no body is answered the same way. Premium subscribers send their agent key as Authorization: Bearer tvr_k_... instead of a payment (one counted Premium operation; 200 directly, no 402).

## Headers

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

## Request body

- object
  - `weights` union: Up to 8 numbers (0-100) in this order: economic_model, network_security, adoption, privacy, longevity, liquidity, legal_clarity, technical_dev. Missing entries take TVR defaults. An object keyed by those metric names is also accepted. All-zero weights and fewer than three metrics at weight 3 or more are refused.
    - number[]
    - object
  - `coins` string[]: Optional tickers or names (1-50). Omit for all covered coins.

## Response `200`

Paid and delivered. The ranking under the caller's weights, with the settlement receipt in PAYMENT-RESPONSE.

- object
  - `success` boolean
  - `product` string
  - `count` integer
  - `rankings` object[]
    - `rank` integer
    - `symbol` string
    - `name` string
    - `tvr_score` number
    - `valuation` 'undervalued' | 'fair_value' | 'overvalued'
    - `fair_value_gap_pct` number
    - `tvr_estimated_value_usd` number
    - `score_rank` integer
  - `weights_used` object: The 8 weights applied, keyed by metric name
  - `weights_array` number[]
  - `defaults_applied_for` string[]: Metric names whose weight was missing and took the TVR default
  - `legal` object: Nature of the output, attribution requirement, licence
  - `context` string
  - `disclaimer` string
  - `attribution` string

## Other responses

- `400`: Invalid input (weights out of range, all-zero, fewer than three metrics at weight 3 or more, unknown coin). 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)