From 571c47cc88b25fa2360c0d5bc596f58504a682d4 Mon Sep 17 00:00:00 2001 From: Etienne Donneger Date: Tue, 12 May 2026 16:57:45 -0400 Subject: [PATCH] docs(schema): clarify value field is decimal-scaled, not USD MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The `value` field returned on balances, holders, and transfers endpoints (EVM/SVM/TVM, regular and native) is computed as `amount / 10^decimals` — the human-readable token amount, not a USD valuation. The label was previously undocumented, leading consumers to interpret large balances as dollar values. Add a description on each schema so the OpenAPI export and SDK types make the semantics explicit. No behavioural change; same numbers are returned. Polymarket activity intentionally excluded — its `value` is USDC and genuinely is a dollar amount given USDC's 6 decimals. Co-Authored-By: Claude Opus 4.7 (1M context) --- src/routes/balances/evm.ts | 2 +- src/routes/balances/evm_native.ts | 2 +- src/routes/balances/svm.ts | 2 +- src/routes/balances/svm_native.ts | 2 +- src/routes/balances/tvm.ts | 2 +- src/routes/balances/tvm_native.ts | 2 +- src/routes/holders/evm.ts | 2 +- src/routes/holders/evm_native.ts | 2 +- src/routes/holders/svm.ts | 2 +- src/routes/holders/svm_native.ts | 2 +- src/routes/holders/tvm.ts | 2 +- src/routes/holders/tvm_native.ts | 2 +- src/routes/transfers/evm.ts | 2 +- src/routes/transfers/evm_native.ts | 2 +- src/routes/transfers/svm.ts | 2 +- src/routes/transfers/svm_native.ts | 2 +- src/routes/transfers/tvm.ts | 2 +- src/routes/transfers/tvm_native.ts | 2 +- 18 files changed, 18 insertions(+), 18 deletions(-) diff --git a/src/routes/balances/evm.ts b/src/routes/balances/evm.ts index e19531f7..960f9c95 100644 --- a/src/routes/balances/evm.ts +++ b/src/routes/balances/evm.ts @@ -42,7 +42,7 @@ const responseSchema = apiUsageResponseSchema.extend({ address: evmAddressSchema, contract: evmContractSchema, amount: z.string(), - value: z.number(), + value: z.number().describe('Decimal-scaled token amount (= amount / 10^decimals). Not a USD value.'), // -- contract -- name: z.string().nullable(), diff --git a/src/routes/balances/evm_native.ts b/src/routes/balances/evm_native.ts index ca562997..27bcc2b5 100644 --- a/src/routes/balances/evm_native.ts +++ b/src/routes/balances/evm_native.ts @@ -34,7 +34,7 @@ const responseSchema = apiUsageResponseSchema.extend({ // -- balance -- address: evmAddressSchema, amount: z.string(), - value: z.number(), + value: z.number().describe('Decimal-scaled token amount (= amount / 10^decimals). Not a USD value.'), // -- contract -- name: z.string().nullable(), diff --git a/src/routes/balances/svm.ts b/src/routes/balances/svm.ts index d5c84c24..b086d5fc 100644 --- a/src/routes/balances/svm.ts +++ b/src/routes/balances/svm.ts @@ -46,7 +46,7 @@ const responseSchema = apiUsageResponseSchema.extend({ // -- amount -- amount: z.string(), - value: z.number(), + value: z.number().describe('Decimal-scaled token amount (= amount / 10^decimals). Not a USD value.'), decimals: z.number().nullable(), // -- mint metadata -- diff --git a/src/routes/balances/svm_native.ts b/src/routes/balances/svm_native.ts index ae3a0d0c..d403aa9a 100644 --- a/src/routes/balances/svm_native.ts +++ b/src/routes/balances/svm_native.ts @@ -43,7 +43,7 @@ const responseSchema = apiUsageResponseSchema.extend({ mint: svmMintSchema, amount: z.string(), - value: z.number(), + value: z.number().describe('Decimal-scaled token amount (= amount / 10^decimals). Not a USD value.'), decimals: z.number().nullable(), name: z.string().nullable(), diff --git a/src/routes/balances/tvm.ts b/src/routes/balances/tvm.ts index 0b896d8c..3e33e638 100644 --- a/src/routes/balances/tvm.ts +++ b/src/routes/balances/tvm.ts @@ -42,7 +42,7 @@ const responseSchema = apiUsageResponseSchema.extend({ address: evmAddressSchema, contract: evmContractSchema, amount: z.string(), - value: z.number(), + value: z.number().describe('Decimal-scaled token amount (= amount / 10^decimals). Not a USD value.'), // -- contract -- name: z.string().nullable(), diff --git a/src/routes/balances/tvm_native.ts b/src/routes/balances/tvm_native.ts index 22901317..a3fa2a5d 100644 --- a/src/routes/balances/tvm_native.ts +++ b/src/routes/balances/tvm_native.ts @@ -36,7 +36,7 @@ const responseSchema = apiUsageResponseSchema.extend({ // -- balance -- address: evmAddressSchema, amount: z.string(), - value: z.number(), + value: z.number().describe('Decimal-scaled token amount (= amount / 10^decimals). Not a USD value.'), // -- contract -- name: z.string().nullable(), diff --git a/src/routes/holders/evm.ts b/src/routes/holders/evm.ts index a42fe51e..96fb1ab8 100644 --- a/src/routes/holders/evm.ts +++ b/src/routes/holders/evm.ts @@ -35,7 +35,7 @@ const responseSchema = apiUsageResponseSchema.extend({ address: evmAddressSchema, contract: evmContractSchema, amount: z.string(), - value: z.number(), + value: z.number().describe('Decimal-scaled token amount (= amount / 10^decimals). Not a USD value.'), // -- contract -- name: z.string().nullable(), diff --git a/src/routes/holders/evm_native.ts b/src/routes/holders/evm_native.ts index c2eacab4..0382085d 100644 --- a/src/routes/holders/evm_native.ts +++ b/src/routes/holders/evm_native.ts @@ -30,7 +30,7 @@ const responseSchema = apiUsageResponseSchema.extend({ // -- contract -- address: evmAddressSchema, amount: z.string(), - value: z.number(), + value: z.number().describe('Decimal-scaled token amount (= amount / 10^decimals). Not a USD value.'), // -- contract -- name: z.string().nullable(), diff --git a/src/routes/holders/svm.ts b/src/routes/holders/svm.ts index dd00a97e..8281ece8 100644 --- a/src/routes/holders/svm.ts +++ b/src/routes/holders/svm.ts @@ -42,7 +42,7 @@ const responseSchema = apiUsageResponseSchema.extend({ // -- amount -- amount: z.string(), - value: z.number(), + value: z.number().describe('Decimal-scaled token amount (= amount / 10^decimals). Not a USD value.'), decimals: z.number(), // -- metadata -- diff --git a/src/routes/holders/svm_native.ts b/src/routes/holders/svm_native.ts index 23bfaa20..212f84f2 100644 --- a/src/routes/holders/svm_native.ts +++ b/src/routes/holders/svm_native.ts @@ -38,7 +38,7 @@ const responseSchema = apiUsageResponseSchema.extend({ // -- amount -- amount: z.string(), - value: z.number(), + value: z.number().describe('Decimal-scaled token amount (= amount / 10^decimals). Not a USD value.'), decimals: z.number(), // -- metadata -- diff --git a/src/routes/holders/tvm.ts b/src/routes/holders/tvm.ts index 9f06bbbf..8de93d5f 100644 --- a/src/routes/holders/tvm.ts +++ b/src/routes/holders/tvm.ts @@ -34,7 +34,7 @@ const responseSchema = apiUsageResponseSchema.extend({ address: evmAddressSchema, contract: evmContractSchema, amount: z.string(), - value: z.number(), + value: z.number().describe('Decimal-scaled token amount (= amount / 10^decimals). Not a USD value.'), // -- contract -- name: z.string().nullable(), diff --git a/src/routes/holders/tvm_native.ts b/src/routes/holders/tvm_native.ts index de9705ff..3c089761 100644 --- a/src/routes/holders/tvm_native.ts +++ b/src/routes/holders/tvm_native.ts @@ -30,7 +30,7 @@ const responseSchema = apiUsageResponseSchema.extend({ // -- contract -- address: evmAddressSchema, amount: z.string(), - value: z.number(), + value: z.number().describe('Decimal-scaled token amount (= amount / 10^decimals). Not a USD value.'), // -- contract -- name: z.string().nullable(), diff --git a/src/routes/transfers/evm.ts b/src/routes/transfers/evm.ts index 5754a092..30184ab1 100644 --- a/src/routes/transfers/evm.ts +++ b/src/routes/transfers/evm.ts @@ -63,7 +63,7 @@ const responseSchema = apiUsageResponseSchema.extend({ decimals: z.number().nullable(), amount: z.string(), - value: z.number(), + value: z.number().describe('Decimal-scaled token amount (= amount / 10^decimals). Not a USD value.'), // -- chain -- network: evmNetworkIdSchema, diff --git a/src/routes/transfers/evm_native.ts b/src/routes/transfers/evm_native.ts index 2882d452..8538f4bd 100644 --- a/src/routes/transfers/evm_native.ts +++ b/src/routes/transfers/evm_native.ts @@ -59,7 +59,7 @@ const responseSchema = apiUsageResponseSchema.extend({ decimals: z.number().nullable(), amount: z.string(), - value: z.number(), + value: z.number().describe('Decimal-scaled token amount (= amount / 10^decimals). Not a USD value.'), // -- chain -- network: evmNetworkIdSchema, diff --git a/src/routes/transfers/svm.ts b/src/routes/transfers/svm.ts index 3955b91b..0f0fb407 100644 --- a/src/routes/transfers/svm.ts +++ b/src/routes/transfers/svm.ts @@ -111,7 +111,7 @@ const responseSchema = apiUsageResponseSchema.extend({ // -- amount -- amount: z.string(), - value: z.number(), + value: z.number().describe('Decimal-scaled token amount (= amount / 10^decimals). Not a USD value.'), decimals: z.number().nullable(), // -- token metadata -- diff --git a/src/routes/transfers/svm_native.ts b/src/routes/transfers/svm_native.ts index 5d87af93..704e7137 100644 --- a/src/routes/transfers/svm_native.ts +++ b/src/routes/transfers/svm_native.ts @@ -90,7 +90,7 @@ const responseSchema = apiUsageResponseSchema.extend({ // -- amounts -- amount: z.string(), - value: z.number(), + value: z.number().describe('Decimal-scaled token amount (= amount / 10^decimals). Not a USD value.'), decimals: z.number().nullable(), // -- metadata -- diff --git a/src/routes/transfers/tvm.ts b/src/routes/transfers/tvm.ts index 001e4cd2..7aa7d78a 100644 --- a/src/routes/transfers/tvm.ts +++ b/src/routes/transfers/tvm.ts @@ -78,7 +78,7 @@ const responseSchema = apiUsageResponseSchema.extend({ to: tvmAddressSchema, amount: z.string(), - value: z.number(), + value: z.number().describe('Decimal-scaled token amount (= amount / 10^decimals). Not a USD value.'), // -- contract -- name: z.string().nullable(), diff --git a/src/routes/transfers/tvm_native.ts b/src/routes/transfers/tvm_native.ts index 13ddf723..d6a6779d 100644 --- a/src/routes/transfers/tvm_native.ts +++ b/src/routes/transfers/tvm_native.ts @@ -68,7 +68,7 @@ const responseSchema = apiUsageResponseSchema.extend({ to: tvmAddressSchema, amount: z.string(), - value: z.number(), + value: z.number().describe('Decimal-scaled token amount (= amount / 10^decimals). Not a USD value.'), // -- contract -- name: z.string().nullable(),