openfin-onchain
Onchain Token Data
Read-only multi-chain token data through OpenFinance, backed by Uniblock. Use this when an agent needs to know what a token is, what an address holds, or what something is worth in USD before quoting, trading, or displaying anything.
No signing, no wallet writes, no on-chain side effects — just enriched reads across 100+ chains (every major EVM, Solana, Bitcoin, Tron, etc.).
Prerequisite
- User completed
openfin-setup(API key in place —open_…). - All endpoints take
x-api-key: open_….
Endpoints
Token metadata
GET /agent/onchain/token/metadata — Resolve one or many token
contracts into human-readable info: name, symbol, logo URL,
decimals, address, chainId. Use before showing a token to a user,
or to look up decimals before formatting an on-chain raw balance.
| Param | Required | Notes |
|---|---|---|
chainId |
✓ | "1" Ethereum, "137" Polygon, "42161" Arbitrum, "8453" Base, "solana", etc. |
tokenAddress |
✓ | Single contract, comma-separated for batch, or "native" |
includeRaw |
optional | Returns provider-raw payload (disables backup providers) |
provider |
optional | Force Alchemy / GoldRush / Moralis / Tatum / Helius / SolScan / Shyft / Uniblock |
Address portfolio (native + fungibles + NFTs)
GET /agent/onchain/token/portfolio — Full holdings snapshot for
one wallet on one chain. Returns native balance, every fungible token,
and the NFT collection. Heavier than /balances because it enumerates
NFTs.
| Param | Required | Notes |
|---|---|---|
chainId |
✓ | |
walletAddress |
✓ | |
includePrice |
optional | Attach USD values to fungibles |
includeMetadata |
optional | Attach name / symbol / logo / decimals |
includeRaw, provider |
optional |
Use when the agent needs the complete view ("show me everything in
this wallet"). For trade-prep checks, prefer /balances — it's faster.
Address token balances (no NFTs, paginated)
GET /agent/onchain/token/balances — Native + fungible token
balances. Returns balance (raw) and formattedBalance
(human-readable, decimals applied). Paginated via cursor.
| Param | Required | Notes |
|---|---|---|
chainId |
✓ | |
walletAddress |
✓ | |
includePrice |
optional | Attach USD values |
includeMetadata |
optional | Attach token metadata |
cursor |
optional | From a previous response for the next page |
includeRaw, provider |
optional |
Use this before placing trades, computing USD totals, or letting the agent reason about what to swap.
Token USD price
GET /agent/onchain/token/price — Current USD spot price for one or
many tokens. Returns usdPrice, plus name, symbol, decimals,
logo, source exchangeName / exchangeAddress, updatedAt.
| Param | Required | Notes |
|---|---|---|
chainId |
✓ | Comma-separated for cross-chain batch |
contractAddress |
✓ | Single, comma-separated for batch, or native |
exchange |
optional | Pin to uniswap-v2 / uniswap-v3 / sushiswap-v2 / pancakeswap-v1 / pancakeswap-v2 / quickswap |
provider |
optional | Alchemy / GoldRush / Moralis |
includeRaw |
optional |
Use before quoting a swap, computing portfolio USD totals, or suggesting trades.
Common chain IDs
| Chain | ID |
|---|---|
| Ethereum | 1 |
| Polygon | 137 |
| Base | 8453 |
| Arbitrum | 42161 |
| Optimism | 10 |
| BSC | 56 |
| Linea | 59144 |
| Solana | solana |
| Bitcoin | bitcoin |
(Uniblock supports 100+; pass the chain ID/key it expects. For Relay
bridging, see openfin-relay — its chain IDs differ for non-EVM.)
Picking the right endpoint
| Need | Use |
|---|---|
| "What is this contract?" | /token/metadata |
| "What's the USD price?" | /token/price |
| "What does this wallet hold?" (fungibles only) | /token/balances |
| "Show me everything" (incl. NFTs) | /token/portfolio |
Don't call /portfolio when /balances is enough — NFT enumeration is
slow and you usually don't need it.
Example flow — value a wallet's USDC across chains
- For each chain ID the user cares about (e.g.
1,137,8453,42161):GET /agent/onchain/token/balances?chainId=<id>&walletAddress=<addr>&includePrice=true&includeMetadata=true
- Sum
formattedBalance * usdPriceacross the response'sbalancesarray.
For a single token across many chains, /token/price accepts
comma-separated chainId and contractAddress for one round trip.
Don't
- Don't poll
/portfolioper-chain when the user just wants balances —/balancesis much lighter. - Don't pass user-provided "1.5 ETH" as
amount; this skill is read-only. For sends/swaps, seeopenfin-relay. - Don't assume
decimals = 18. Always read it from/metadata(some tokens are 6, 8, 9, etc. — USDC is 6, WBTC is 8, USDT on Ethereum is 6, on BSC is 18). - Don't use this for live trading prices on illiquid pairs — pin
exchangeif you need a specific DEX, and prefer the asset's native market endpoint (openfin-polymarketfor prediction markets,openfin-hyperliquidfor perp/spot mids).
MCP note
Tool names mirror the routes (onchain_ prefix):
onchain_get_token_metadataonchain_get_address_portfolioonchain_get_address_token_balancesonchain_get_token_usd_price
More from openfinance-tech/skills
openfin-relay
Cross-chain bridging, swapping, and "bridge+call" via Relay through the OpenFinance backend. Use whenever the user wants to move tokens between chains or execute a destination-chain transaction funded from another chain. Triggers: "bridge X from Y to Z", "move my USDC to Base / Arbitrum / Optimism / Polygon / Solana", "swap ETH for USDC on Base", "cross-chain swap", "bridge and call", "how do I get to Solana / back from Solana", "my USDC is stuck on Solana", EVM-to-EVM, EVM-to-Solana, Solana-to-EVM, Bitcoin bridge, gas topup on destination, native-token sentinel 0x0, relay quote/preview/execute flow, poll intent status. Covers POST /agent/relay/quote, POST /agent/relay/execute, GET /agent/relay/status. Includes the chainId cheatsheet (1/137/8453/10/42161/... and Solana 792703809 specifically), tradeType semantics (EXACT_INPUT / EXACT_OUTPUT / EXPECTED_OUTPUT), why topupGas is auto-disabled on Solana routes, and bridge+call payloads (txs array). Use together with openfin-setup (API key check) and openfin-troubleshooting (Blockhash not found, Custom:101, 412 setup-incomplete on Solana origin).
24openfin-polymarket
Complete Polymarket playbook covering research and trading on the world's largest prediction market. Use this for ANY Polymarket task. Deposit-wallet model (CRITICAL): Polymarket's CLOB rejects raw EOAs as makers, so each user has a deterministic per-EOA "deposit wallet" smart contract that holds pUSD, carries allowances, and is named as `funder`/`maker`/`signer` on signed orders (POLY_1271 / EIP-1271). pUSD sent directly to the EOA is stranded for trading until it reaches the deposit wallet. Always call `GET /agent/polymarket/deposit-wallet` to get the right address before quoting "where do I deposit", checking balance, or running position queries — and pass the deposit-wallet address (NOT the EOA) as `:address` for `/user/:address/*` lookups. Research triggers: finding events ("what's happening in politics", "show me election odds", "NBA finals odds", "BTC to 200k markets", "IPL / FIFA / UFC / F1 betting markets"), listing markets with filters, searching by keyword, reading orderbooks, mid prices, spreads, last trade prices, recent trades, open interest, volume, liquidity, and any user's positions/portfolio/PnL by address. Deposit triggers: "where do I deposit on Polymarket", "what's my Polymarket address", "send pUSD to Polymarket", "Polymarket deposit wallet", "is my deposit wallet deployed". Trading triggers: place a bet on YES or NO, buy/sell outcomes, limit orders (GTC/GTD), market orders (FOK/FAK), batch orders, cancel one/many/all orders, check and set on-chain pUSD and CTF approvals, neg-risk (multi-outcome) markets, tick size handling (0.01/0.001/0.0001), and builder-code attribution. Covers all routes under /agent/polymarket/* (events, markets, search, orderbook, price, prices, spread, last-trade-price, trades, market/:id/open-interest|volume|liquidity|trades, user/:address/positions|trades|portfolio|pnl, deposit-wallet, order, order/market, orders, order/:id, order/:id/scoring, approvals, builder/*). Use when the user mentions Polymarket, prediction markets, event betting, binary outcomes, probability markets, YES/NO tokens, conditional tokens, or politics/sports/crypto/culture odds. Prerequisite: openfin-setup for trading.
24openfin-setup
Auth check for the OpenFinance backend — confirms an API key is available before any other OpenFinance skill runs. Use FIRST whenever the user is about to call any /agent/* route (Polymarket, Hyperliquid, Relay), is hitting 401/412, or hasn't traded yet in this session. Triggers on "how do I get started", "API key is required", "Invalid API key", "401/412 from /agent/*", "set up OpenFinance", or any first call into a trading skill. Resolves the key from `OPENFINANCE_API_KEY` (or equivalent env / user-supplied value), confirms the format (`open_…`), verifies via GET /agent/wallets, and otherwise points the user to https://openfinance.tech to issue one.
23openfin-hyperliquid
>-
23openfin-troubleshooting
>-
23openfin-onramp
Fiat-to-crypto onramp via Moonpay, prefilled with the caller's wallet, chain, currency, and fiat amount. Use whenever the user says they want to buy crypto with a card / bank / Apple Pay / Google Pay, top up a wallet from fiat, fund a Hyperliquid / Polymarket / Solana wallet "with my card", or "I'm out of USDC, how do I get some". Triggers: "buy USDC with my card", "credit card onramp", "Apple Pay USDC", "deposit fiat", "I have no crypto, how do I start", "fund my wallet with fiat", "buy ETH on Base with USD". Covers POST /agent/onramp/moonpay — returns a Moonpay simple-URL with chain / currencyCode / walletAddress / fiat amount baked in. The user opens the URL to complete KYC + payment in Moonpay's UI; once the buy clears, funds arrive in the user's OpenFinance-provisioned wallet on the chosen chain. No on-chain signing from the agent. Wallet defaults to the caller's OpenFinance-managed EVM address (or Solana address when chain=solana / currencyCode ends `_sol`). Pair with openfin-relay (bridge after onramp lands on a different chain than where you want to trade) and openfin-setup (API key check).
14