API Reference · TokenSee

#Overview

The TokenSee API is a REST interface for on-chain blockchain data. It abstracts chain complexity — RPC nodes, ABI decoding, price feeds, log parsing — into simple, typed JSON responses.

All endpoints return JSON. Request bodies use application/json. Responses follow a consistent envelope: { success, data } on success or { success: false, error: { code, message } } on failure.

#Base URL

text

https://api.tokensee.com

All endpoints are versioned under /v1. Development: http://localhost:8080/v1（与根目录 .env 中 PORT 一致）

#Authentication

Pass your API key in the X-Api-Key request header. Keys can be created in the dashboard (coming soon). During development, the header is optional.

http

POST /v1/tx/decode HTTP/1.1
Host: api.tokensee.com
Content-Type: application/json
X-Api-Key: tsk_live_xxxxxxxxxxxxxxxxxxxx

#Errors

Error responses always have success: false and an error object with a machine-readable code.

json

{
  "success": false,
  "error": {
    "code": "INVALID_HASH",
    "message": "Transaction hash must be 66 hex characters"
  }
}

Code	HTTP	Meaning
INVALID_HASH	400	Malformed transaction hash
INVALID_ADDRESS	400	Malformed Ethereum address
INVALID_CHAIN	400	Chain not in supported list
TX_NOT_FOUND	404	Hash not found on the specified chain
DECODE_FAILED	422	Transaction found but could not be decoded
RATE_LIMITED	429	Too many requests — back off and retry
INTERNAL_ERROR	500	Unexpected server error

#Rate Limits

Plan	Requests / min	Requests / day
Free (no key)	10	500
Developer	60	10,000
Pro	300	100,000
Enterprise	Unlimited	Unlimited

Rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (Unix timestamp).

POST/v1/tx/decode

Description

Decodes a transaction hash into a structured, human-readable result. Includes transaction type, protocol, assets moved (with USD values), gas cost, and a one-line English summary.

Results are cached in Redis for 10 minutes. The cached flag in the response indicates a cache hit.

Request Body

Parameter	Type	Required	Description
hash	string	required	66-character hex transaction hash (0x-prefixed)
chain	"ethereum" \| "bsc"	required	Which chain to query

json

{
  "hash": "0x3ca204e45e3801a19cd0217b70fdd33eb0af6cf3e7310878f19ee216e5ff329e",
  "chain": "ethereum"
}

Response

json

{
  "success": true,
  "data": {
    "hash": "0x3ca204e45e3801a19cd0217b70fdd33eb0af6cf3e7310878f19ee216e5ff329e",
    "chain": "ethereum",
    "block_number": 21936620,
    "timestamp": 1740636671,
    "sender": "0x1a2b3c4d5e6f7890abcdef1234567890abcdef12",
    "contract_address": "0x3fc91a3afd70395cd496c647d5a6cc9d4b2b7fad",
    "type": "swap",
    "protocol": "uniswap-universal",
    "protocol_version": null,
    "summary": "Swapped 0.5 ETH for 1,482.30 USDC via Uniswap",
    "assets_in": [
      {
        "address": "0x0000000000000000000000000000000000000000",
        "symbol": "ETH",
        "decimals": 18,
        "amount": "0.5",
        "amount_raw": "500000000000000000",
        "amount_usd": "1490.25"
      }
    ],
    "assets_out": [
      {
        "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "symbol": "USDC",
        "decimals": 6,
        "amount": "1482.30",
        "amount_raw": "1482300000",
        "amount_usd": "1482.30"
      }
    ],
    "gas_used": "184520",
    "gas_price_gwei": "12.4",
    "fee_eth": "0.002288",
    "fee_usd": "6.82",
    "function_name": "execute",
    "function_args": null,
    "decode_method": "known_abi"
  },
  "cached": false,
  "decode_latency_ms": 142
}

Field Reference

Field	Type	Description
type	TransactionType	Semantic type — see Types section
protocol	string \| null	Protocol identifier (e.g. "uniswap-v3")
summary	string	One-line English description of the transaction
assets_in	AssetAmount[]	Assets consumed by the sender
assets_out	AssetAmount[]	Assets received by the sender
fee_eth	string	Gas fee in native token (ETH or BNB)
fee_usd	string \| null	Gas fee in USD (null if price unavailable)
decode_method	DecodeMethod	How the ABI was resolved — see Types section
cached	boolean	True if served from Redis cache
decode_latency_ms	number	End-to-end decode time in milliseconds

Try it

Transaction Hash

Chain

GET/v1/account/:address/portfolio

Description

Returns the complete token portfolio for an address across all specified chains. Includes native token balance, ERC-20 holdings (via Alchemy), real-time USD prices, and per-chain totals.

Path Parameters

Parameter	Type	Required	Description
address	string	required	Checksummed or lowercase Ethereum-compatible address

Query Parameters

Parameter	Type	Required	Description
chains	string	optional	Comma-separated chain list. Default: "ethereum,bsc"

http

GET /v1/account/0x1a2b...ef12/portfolio?chains=ethereum,bsc

Response

json

{
  "success": true,
  "data": {
    "address": "0x1a2b3c4d5e6f7890abcdef1234567890abcdef12",
    "chains": [
      {
        "chain": "ethereum",
        "native": {
          "address": "0x0000000000000000000000000000000000000000",
          "symbol": "ETH",
          "name": "Ethereum",
          "decimals": 18,
          "balance": "1.234567",
          "balance_raw": "1234567000000000000",
          "price_usd": "2980.50",
          "value_usd": "3680.19"
        },
        "tokens": [
          {
            "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
            "symbol": "USDC",
            "name": "USD Coin",
            "decimals": 6,
            "balance": "5000.00",
            "balance_raw": "5000000000",
            "price_usd": "1.00",
            "value_usd": "5000.00",
            "logo": "https://static.alchemyapi.io/images/assets/3408.png"
          }
        ],
        "total_value_usd": "8680.19"
      },
      {
        "chain": "bsc",
        "native": { "symbol": "BNB", "balance": "2.5", "value_usd": "1537.50" },
        "tokens": [],
        "total_value_usd": "1537.50"
      }
    ],
    "total_value_usd": "10217.69"
  }
}

Notes

·ERC-20 token enumeration on Ethereum uses Alchemy. BSC token list returns empty until BSCScan integration is added.
·Tokens with zero balance are filtered out. Results are sorted by USD value descending.
·Prices are fetched from CoinGecko with a 5-minute Redis cache. value_usd is null for tokens without a known price.
·Portfolio results are cached for 5 minutes per address+chains combination.

Try it

Wallet Address

Chains (comma-separated)

GET/v1/account/:address/activityComing Soon

Description

Returns a paginated list of decoded transactions for an address, sorted by block time descending. Each item is the same shape as a /tx/decode response.

Query Parameters

Parameter	Type	Required	Description
chains	string	optional	Comma-separated. Default: "ethereum,bsc"
limit	number	optional	Results per page (1–100). Default: 20
cursor	string	optional	Pagination cursor from previous response
type	TransactionType	optional	Filter by transaction type

Response Shape

json

{
  "success": true,
  "data": {
    "items": [ /* DecodedTransaction[] */ ],
    "cursor": "eyJibG9jayI6MjE5MzY2MjAsImluZGV4IjoxMn0",
    "has_more": true
  }
}

Try it

Chain (optional)

Limit

#Data Types

TransactionType

Value	Description
swap	Token swap via DEX
transfer	Native or ERC-20 token transfer
liquidity_add	Adding liquidity to a pool
liquidity_remove	Removing liquidity from a pool
borrow	Borrowing from a lending protocol
repay	Repaying a loan
stake	Staking tokens
nft_mint	Minting an NFT
nft_transfer	Transferring an NFT
contract_deploy	Deploying a contract
contract_interaction	Generic contract call
unknown	Could not determine type

DecodeMethod

Value	Description
known_abi	Decoded using a bundled ABI for a known protocol address
four_byte	Function signature resolved via 4byte.directory
event_only	No input decode; assets reconstructed from ERC-20 Transfer logs
raw	No decode possible; raw transaction data only

AssetAmount

Field	Type	Description
address	string	0x0000...0000 for native token, contract address for ERC-20
symbol	string	Token ticker (ETH, USDC, etc.)
decimals	number	Token decimal places
amount	string	Human-readable amount (formatUnits applied)
amount_raw	string	Raw integer amount as decimal string
amount_usd	string \| undefined	USD equivalent at time of decode

#Supported Chains

Chain	ID	Native	RPC Provider	Token Enumeration
Ethereum	ethereum	ETH	Alchemy	✓ via alchemy_getTokenBalances
BNB Chain	bsc	BNB	QuickNode / Public	— (coming via BSCScan)

#Supported Protocols

ID	Chain	Contracts
uniswap-v3	Ethereum	SwapRouter, SwapRouter02
uniswap-universal	Ethereum	UniversalRouter v1 & v2
uniswap-v2	Ethereum	UniswapV2Router02
pancakeswap-v2	BSC	PancakeRouter
pancakeswap-v3	BSC	SmartRouter
aave-v3	Ethereum	Pool (handler in progress)

Unknown protocols fall back to event-only decode using ERC-20 Transfer logs.