Wallet value in USDWallet value in USDReturns JSON with a wallet's USD value on Ethereum and Base in one call: native and major-token balances priced on-chain from Uniswap v3 pools on Base, per-chain totals and the tokens left unpriced.
Use when you need a wallet portfolio value in USD, a wallet net worth or token balances with USD value for a 0x address.
Do not use for Solana wallets, transaction history, NFTs, DeFi positions or long-tail tokens.
Price: 0.005 USDC per call (x402, eip155:8453). Typical response time: 5000 ms (p95).
POST https://x402-gateway.blackwoodstate8.workers.dev/v1/wallet-value. A request without payment gets 402 Payment Required with the
PAYMENT-REQUIRED header; any x402 client signs an EIP-3009 authorization and retries with
PAYMENT-SIGNATURE (or X-PAYMENT). Invalid input is answered with 400 and not charged.
curl -i -X POST https://x402-gateway.blackwoodstate8.workers.dev/v1/wallet-value -H 'content-type: application/json' -d '{"address":"0x87DB3C25d1E8E40f8EF240D48a711B0C355CF8Cf","chains":["base"]}'
| Pay to | 0x703aA725EBd995B3F32BB5132Effa8B90FCc2165 |
|---|---|
| Asset | 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 (USDC) |
| Amount | 5000 atomic units (0.005 USDC) |
| Authorization window | 60 s |
Streamable HTTP at https://x402-gateway.blackwoodstate8.workers.dev/mcp, tool blackwood_wallet_value. Payment goes in
_meta["x402/payment"]; without it the tool returns the payment requirements.
| Field | Type | Meaning |
|---|---|---|
address | string | Wallet address (0x...) on Ethereum and Base, e.g. 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 |
chains (optional) | array | Chains to value (ethereum and base when omitted), e.g. ["base"] |
Example:
{
"address": "0x87DB3C25d1E8E40f8EF240D48a711B0C355CF8Cf",
"chains": [
"base"
]
}
Real example:
{
"address": "0x87DB3C25d1E8E40f8EF240D48a711B0C355CF8Cf",
"totalUsd": 8.47,
"chains": {
"ethereum": null,
"base": 8.47
},
"holdings": [
{
"chain": "base",
"symbol": "ETH",
"contract": null,
"balance": "0.002360178464231316",
"priceUsd": 2420.0937,
"valueUsd": 5.71
},
{
"chain": "base",
"symbol": "USDC",
"contract": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
"balance": "2.756539",
"priceUsd": 1,
"valueUsd": 2.76
}
],
"unpriced": [],
"errors": {},
"updatedAt": "2026-10-18T04:14:44.193Z",
"note": "USD values use the on-chain price of the same asset on Base: its deepest Uniswap v3 pool against USDC or WETH (USDC counts as 1 USD). Ethereum tokens are priced through their Base counterpart (same issuer or canonical bridge); tokens without one, or without a liquid pool, are listed in unpriced and left out of the totals. Balances cover the native coin and a fixed list of major tokens; values are rounded to cents."
}
{
"type": "object",
"properties": {
"address": {
"type": "string"
},
"totalUsd": {
"type": "number"
},
"chains": {
"type": "object",
"properties": {
"ethereum": {
"type": [
"number",
"null"
]
},
"base": {
"type": [
"number",
"null"
]
}
},
"required": [
"ethereum",
"base"
],
"additionalProperties": false
},
"holdings": {
"type": "array",
"items": {
"type": "object",
"properties": {
"chain": {
"type": "string",
"enum": [
"ethereum",
"base"
]
},
"symbol": {
"type": "string"
},
"contract": {
"type": [
"string",
"null"
]
},
"balance": {
"type": "string"
},
"priceUsd": {
"type": [
"number",
"null"
]
},
"valueUsd": {
"type": [
"number",
"null"
]
}
},
"required": [
"chain",
"symbol",
"contract",
"balance",
"priceUsd",
"valueUsd"
],
"additionalProperties": false
}
},
"unpriced": {
"type": "array",
"items": {
"type": "object",
"properties": {
"chain": {
"type": "string",
"enum": [
"ethereum",
"base"
]
},
"symbol": {
"type": "string"
},
"reason": {
"type": "string"
}
},
"required": [
"chain",
"symbol",
"reason"
],
"additionalProperties": false
}
},
"errors": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
},
"updatedAt": {
"type": "string"
},
"note": {
"type": "string"
},
"next": {
"type": "object",
"properties": {
"service": {
"type": "string",
"description": "Service id of the suggested next paid call"
},
"tool": {
"type": "string",
"description": "MCP tool name of the same call"
},
"method": {
"type": "string",
"enum": [
"GET",
"POST"
]
},
"url": {
"type": "string",
"description": "Paid route of the next call"
},
"useWhen": {
"type": "string",
"description": "When the next call is the right one"
},
"sample": {
"type": "string",
"description": "Free fixed sample of the whole family"
}
},
"required": [
"service",
"tool",
"method",
"url",
"useWhen",
"sample"
],
"additionalProperties": false,
"description": "Suggested next paid call in the same family (call it in a loop when the task continues)"
}
},
"required": [
"address",
"totalUsd",
"chains",
"holdings",
"unpriced",
"errors",
"updatedAt",
"note"
],
"additionalProperties": false
}Free schema and example: GET https://x402-gateway.blackwoodstate8.workers.dev/v1/wallet-value.
OpenAPI 3.1 · llms.txt · All services