A commonly cited trajectory puts crypto-wallet users at 68.42 million in February 2021 and above 420 million by late 2024, about 520% growth in less than four years, and values the global crypto-wallet market at $14.39 billion in 2024, up from $10.93 billion in 2023, a rise of roughly 31.7%, according to TechJury's industry analysis.
Treat those totals as estimates. One person can control several wallets, published studies do not share one definition of a user, and an address records activity without proving who controls it. Hot wallets dominate day-to-day usage, while security is a major reason some holders choose cold storage.
A crypto wallet API in front of that mix should be specified as a data contract. It needs an unambiguous account identifier, raw units with decimal precision, a timestamp or block reference for each figure, and provenance that says which chain produced the value. It also needs a hard boundary between reading public state and authorizing movement of funds.
When that contract is loose, errors survive validation. Two chains can be added into one total, a token amount can shift during decimal conversion, and a stale row can look current because the JSON is well formed. A usable wallet API makes provenance legible and keeps the read-only surface separate from any permission to spend.
Table of Contents
- Crypto Wallet API Endpoints at a Glance
- Endpoint Categories and the Data Models Behind Them
- Authenticate, Budget Credits and Handle Errors
- How to Pull Holdings and Activity for a Wallet
- Integration Patterns and How to Keep Data Fresh
- Normalizing Multi-Chain Data Without Mixing Meanings
- Agent Permissions and Read-Only Boundaries
- Troubleshooting Wrong Totals, Missing Rows and Stale Values
- Pick the Right Access Path for Your Wallet Data
Crypto Wallet API Endpoints at a Glance
Ownership is much wider than monthly use. One 2025 estimate reported 659 million global crypto owners in 2024, while only 30 to 60 million people used a mobile crypto wallet monthly, roughly 5% to 10% of the 617 million holders tracked by a16z in late 2024, according to CoinLaw's wallet adoption statistics. A balance lookup and a transfer history answer different questions, so they should not share one blob of JSON.
| Endpoint family | Input | Returns |
|---|---|---|
| Address and identity lookup | Wallet address with chain ID | Chain, account type, labels where known |
| Balances | CAIP-10 account identifier | Native and token balances per network |
| Holdings and positions | CAIP-10 account identifier | Open positions, cost basis, unrealized PnL |
| Transaction history | Account plus time or block range | Transfers, swaps, status, timestamps |
| Token ownership | Token contract plus chain | Holder count, top-holder concentration |
| Trader profile | Trader handle or wallet address | Linked wallets, realized PnL, win rate |
| Token flows | Token plus time window | Buys, sells, volume, net flow |
| Watchlist alerts | Saved wallet or token list | Change events pushed on a schedule |
| Composite report | Token or wallet | Several endpoint results combined, with total cost |
How a row actually behaves
Take balances. You send a CAIP-10 account identifier, not a bare hex string. The response lists native and token balances per network, each still tied to that chain. You don't sum them until a later step says the units match.
Cost follows the shape of the call. A single lookup is one call. A paged history costs one call per page. A composite report runs several families and bills the sum. If you loop a composite over a watchlist, the bill is wallets times underlying calls, not wallets times one.
A check you can run today
Pick one public wallet. Call a balance endpoint and a transaction endpoint on the same chain. Before you compare any amounts, confirm both responses report the same chain identifier and the same account address. If either field is missing, stop. The numbers aren't safe to join yet.
Endpoint Categories and the Data Models Behind Them
An address string is not a global primary key. CAIP-10 defines an account identifier as a CAIP-2 blockchain identifier, a colon, and a chain-specific account address (chain_id:account_address). The address stays case-sensitive and may use syntax that doesn't look like an EVM hex string. The same visible characters can mean different accounts on different chains.
Store the full identifier as the lookup key. Keep the original address for display. Normalize only where that chain's rules say normalization is safe. CAIP-10 doesn't require canonicalization everywhere, and it flags deduplication and homograph risk, including URL-encoding of permitted non-alphanumeric characters. Validate the chain namespace. Reject a bare address unless the caller set a default chain in the same request. Return both chain_id and account_address on the way out. Holdings, PnL, token flows, alerts, and trader profiles stay comparable only if you never drop that pair.
What each category is for
Identity answers "which account, on which chain, and what type is it?" Core fields are chain, account address, account type, and any label you can defend.
Holdings answer "what is open, at what cost, and what is still unrealized?" You need raw balance, decimals, asset type, position state, and a price source.
Activity answers "what moved, in which block window, and did it succeed?" Transfers, swaps, status, and timestamps belong here, not inside a balance row.
Token-level data answers "who holds this contract, and how concentrated is it?" Input is the token contract plus chain, not a wallet.
Trader and whale data answers "which wallets sit behind this handle, and what did closed trades earn?" A handle is not an address until you resolve it.
Alerts answer "what changed since the last saved list?" They push events. They don't replace a full history pull.
Fields worth checking on every payload
| Field | Meaning | Example |
|---|---|---|
| chain_id | CAIP-2 network identifier | eip155:1 |
| account_address | Address in the chain's own format | 0xAbC12...9fE4 |
| balance_raw | Integer amount before decimals are applied | 1500000 |
| decimals | Token precision used for display | 6 |
| asset_type | Native, token or wrapped asset | wrapped |
| position_state | Open, realized or estimated | open |
| observed_at | Block number or snapshot time the value reflects | block 21000000 |
| price_source | Where the USD value came from | DEX pool quote |
balance_raw of 1500000 with decimals of 6 displays as 1.5. Apply decimals once, at display time. Position state changes the PnL sentence. An open position is still unrealized. A realized figure comes from closed trades. An estimated figure is a model, not a fill. Mixing those three into one "profit" column is how a report lies with clean arithmetic.
Practical rule: If a response lacks
chain_idoraccount_address, don't join it to anything else. Fix the key before you touch the amounts.
Authenticate, Budget Credits and Handle Errors
Create one account, copy its API key, and send that key in the header the account docs name. Don't put the key in a browser bundle or a public repository. One account and one credit balance cover both MCP and REST, so a chat tool and a script draw from the same budget. Check the credit cost of each endpoint family before a loop starts.
Spend rules that keep a job from running away
One lookup, one call. Identity or a single balance is the cheap path.
A composite report sums its parts. The response should show total credits spent, not hide them inside a "one report" label.
History is per page. Store the cursor. The next run continues there instead of rebuying page one.
Rate limits want space, not a stampede. After a throttle, back off. An immediate retry spends the same failure again.
Failures are not empty wallets
A rejected request is a failure. A valid response with no rows is an empty result. Don't coerce either into zero.
Map provider errors into stable REST and MCP categories: unsupported method, invalid identifier, rate limited, and upstream unavailable. Keep the original RPC code and message in the log. An unsupported method must stay its own category. If you collapse it into a blank balance, a later total treats "we couldn't ask" as "the wallet holds nothing."
Log every failure with the account identifier and a timestamp. When a chain switch and a bad key happen in the same hour, that pair is what tells them apart.
How to Pull Holdings and Activity for a Wallet
A wallet pull is a sequence of small, typed requests: identifier in, balances out, then positions, then history. The picture below is the short version. The slip named under each step is where totals usually break.

All of the REST examples below use the Data API base. One host serves every chain, and the chain travels inside the request as a parameter.
Resolve the account to a CAIP-10 identifier, with the chain set in the request. A Solana address and an EVM address don't share a namespace just because both arrived as strings. The usual slip is accepting a bare address because it "looks like" the chain you had open yesterday. For a Solana-shaped check before you script anything, walk through how to check Solana wallet holdings on one public address.
Fetch balances per chain, and keep
balance_rawbesidedecimals. Example: a GET to that base for the balances resource, with the CAIP-10 id as the account parameter, one chain per call. The slip is dividing by decimals in the client and then dividing again in the chart.Pull holdings and positions, and mark each row open or realized. Example: a GET to the holdings resource for the same identifier. The slip is treating a closed trade's realized PnL as if the position were still open.
Page transaction history by block or time range, and store the cursor. Example: a GET to the history resource with
from_blockand a page size, then the next call sends the cursor you saved. The slip is restarting at the newest page and double-counting transfers.Convert raw balances with token decimals, and attach
price_sourceto every USD figure. Example: a GET to the price resource for that token and chain, stored next to the raw amount, not merged into it. The slip is one global price for a wrapped asset and its native cousin.Compute realized PnL from closed trades, and unrealized PnL from open positions against cost basis. Example: a GET to the positions resource, then subtract cost basis only on rows whose state is open. The slip is one blended "PnL" that adds realized dollars to an unrealized mark.
Write
observed_aton every result before it reaches a cache. Example: persist the block or snapshot time from the response alongside each row. A token snapshot works the same way: it captures price, market cap, total holders, top10 concentration and tracked holders at a point in time, and each snapshot has to be saved because there is no history endpoint to replay it from.
An empty body means you don't know. A zero balance means the chain reported zero at that block. Those are different facts.
Composite reports call several of these resources and should return the total credits spent in the response. A full token memo, the kind that bundles buy and sell flow, holder concentration, tracked smart-money holders and deployer positions into one call, costs the sum of its underlying calls, so it belongs in a scheduled job or a one-off query rather than a tight loop. If this pull eventually feeds a portfolio display instead of a warehouse, how to choose a crypto portfolio tracker lays out whether that screen keeps chain, units and observation time separate or flattens them into one number.
One boundary survives every step. These calls report transactions and balances as the chain recorded them. They do not prove who controls the wallet or why a trade happened, so keep attribution as a label on the data and never as a conclusion.
Integration Patterns and How to Keep Data Fresh
| Pattern | Best for | Trade-off |
|---|---|---|
| Synchronous REST call | Dashboards, scripts and backfills | You manage retries, paging and rate limits |
| MCP tool call from a chat assistant | Plain-language research on wallets and tokens | Results depend on the assistant session and its context |
| Composite endpoint | One full report on a token or trader | Total cost is the sum of the underlying calls |
| Scheduled polling | Watchlists and alerts | Data is stale between polls |
| Provider wrapper | Dapp frontends with a connected wallet | Chain and account must be handled explicitly |
REST fits a backfill because you control the cursor. A chat tool fits a one-off question and then forgets the cursor when the session ends. A composite fits a single memo, not a cron. Polling fits a watchlist and is idle between runs. A provider wrapper fits a dapp that already has a connected wallet, and it fails if you still read window.ethereum as if it were a database.
What "fresh" actually means
EIP-1193 defines a small, event-driven provider: a request method and five standard events, including connectivity, chain changes, account changes, and message notifications. Every request resolves with the RPC result or rejects. Unsupported finalized methods should generally return provider error 4200, which you surface as "unsupported method," not as an empty wallet.
For read-only analytics, wallet identity, chain, and RPC access are request-scoped inputs. The spec doesn't require a browser global. If you later add signing, keep the read path separate. Return a structured transaction or message for the wallet to approve. Never accept a private key.
Treat chainChanged and accountChanged as cache invalidation. Drop balances, positions, and token-flow rows that belonged to the previous account or network. Normalize the provider error into the same REST and MCP categories you already log, and keep the original RPC code beside them.
Alert bots and dashboards can watch tracked traders, token flows, and new launches on a schedule and push changes to where you already look. A poll result is a snapshot with a timestamp. Store it with observed_at. A later comparison without that field is two photos you can't date.
Normalizing Multi-Chain Data Without Mixing Meanings
Supporting more networks doesn't make wallet rows comparable. Ethereum's account-abstraction roadmap is a good place to see why. ERC-4337 adds a smart-account route without changing Ethereum's core protocol. EIP-7702 lets an existing externally owned account act temporarily like a smart account. Those paths differ in transaction flow, authorization, and what an indexer can observe. Ethereum-compatible account abstraction doesn't, by itself, bridge a separate chain.
The question isn't "which chains are in the catalog?" It's whether balances, cost basis, PnL, wallet identity, token flows, and status can be compared without mixing meanings.

Provenance a row should carry
A useful payload names the chain, the block or snapshot time, the finality state, the decimal rule, the wrapped-versus-native relationship, the pricing source, an attribution confidence, and whether the position is open, realized, or estimated. Agents that act across networks need those boundaries before they treat two rows as one fact. Our cross-chain tools are built around that split: one interface, chain-specific meaning left intact.
Say a wallet holds native ETH on Ethereum and a wrapped representation on a second network. A normalized "ETH balance" that adds them with no relationship rule reports one holding. The explorer on each chain will not. The schema didn't remove the difference. It hid it. A single normalized schema raises analytical risk when confidence and chain behavior disappear.
On-chain activity shows transactions and balances. It doesn't prove who controls a wallet, why someone traded, or what happens next. If a field can't carry that limit, the response should say the limit in prose. Otherwise a reader will treat a transfer as a motive.
Agent Permissions and Read-Only Boundaries
A sentence like "buy this" is not an approval. A crypto wallet API that blurs that line will let an agent spend against stale state and leave no record of who allowed it.

Recent work on agentic wallets, summarized in this arXiv paper on agent permissions, treats account abstraction as a shift from a static private key to programmable validation. That shift raises concrete design questions: session keys, spending limits, human approval, replay protection, and revocation. Ethereum's account-abstraction model also separates user operations from bundled transactions, so an execution API has to expose simulation, status, fee sponsorship, and failure diagnosis. Faster automation is worse integration when nobody can see which policy allowed the action, or whether the agent used yesterday's account.
Read-only first
Wallet intelligence APIs read public state. Execution APIs build or submit transactions. Keep them apart.
Permissions are per tool, not per assistant. A research tool that can also submit is an execution tool with a friendly name.
Return a simulation and a policy decision before any write. The simulation is what would happen. The policy decision is whether it may happen. They are not the same object.
Audit logs name the agent, the policy, and the state. "The bot bought" is not an audit record. You need which agent asked, which policy matched, and which observed_at it used.
Research tools only read public data and never ask for your keys. Trading tools use a separate agent wallet that you fund. StalkChain reports what wallets did, such as who bought, who sold, and what they wrote. You make the decision. That is not financial advice.
Natural-language intent is not authorization. If the API's shape implies that a request to move funds is already approved, the shape is wrong.
Before you connect an agent, run three checks. Which tools are read-only? Which policy applies to anything that writes? Where does the audit log live, and can you open it after the session ends?
Troubleshooting Wrong Totals, Missing Rows and Stale Values
Match the symptom to the contract, then open the section that owns the rule. Restating the rule here usually produces a second, slightly different rule.
| Concept | Read next | Symptom it explains |
|---|---|---|
| CAIP-10 identifiers | Endpoint Categories and the Data Models Behind Them | Missing rows or results from the wrong chain |
| Normalization | Normalizing Multi-Chain Data Without Mixing Meanings | Totals that do not match the explorer |
| Provider boundary | Integration Patterns and How to Keep Data Fresh | Balances showing an account from before a switch |
| Read-only policy | Agent Permissions and Read-Only Boundaries | An agent acting without a recorded approval |
| Composite reports | How to Pull Holdings and Activity for a Wallet | Higher credit use than single calls suggested |
| Snapshots versus history | Integration Patterns and How to Keep Data Fresh | Change over time cannot be seen from one result |
Where to look first
Wrong totals. Compare one chain, one block, against a block explorer. If the explorer matches the raw integer and your UI doesn't, decimals were applied twice or two chains were added.
Missing rows. Look at the key you sent. A bare address with no chain, or a stored string that dropped the chain prefix, queries a different account than the one on your screen.
Odd values that were fine an hour ago. Read observed_at before you blame the endpoint. A snapshot from before a chain switch still looks like a balance.
A credit bill that jumped. You called a composite. Its cost is the sum of the inner calls, and a loop multiplies that sum.
Short labels
PnL is profit or loss. Realized PnL comes from closed trades. Unrealized PnL is open-position value minus cost basis. CAIP-2 identifies a blockchain. CAIP-10 identifies an account on a chain. EIP-1193 is the minimal provider interface for EVM wallets. ERC-4337 adds smart accounts without changing Ethereum's core protocol. EIP-7702 lets an existing externally owned account act temporarily like a smart account.
Pick the Right Access Path for Your Wallet Data

StalkChain Data is delivered two ways, MCP and REST API, from one account and one credit balance. You don't have to pick a single path forever. Use MCP when a supported assistant should answer a plain-language question about a wallet or a token. Use REST when you're building dashboards, bots, and backfills. REST works over plain HTTPS, with no MCP client required.
The Wallet Analyzer is free. Look up one public wallet there before you write a client. You'll see whether the identifier, the balance, and the activity story in this guide match what you expected.
First action: pick one public wallet, pull its balance and one page of transactions on the same chain, and confirm both figures against a block explorer. Only then store anything. Before that job runs unattended, apply the identifier checks from the data-model section and the read-only checks from the agent section. A pretty total that fails either check is still a bad total.
StalkChain gives AI assistants and your own apps live wallet holdings, realized and unrealized PnL, token flows, and trader activity through an MCP server and a REST API, without asking research tools for private keys. If you're wiring a crypto wallet API into a dashboard, a bot, or an agent, start with a public address and a read-only call so the identifiers and units are right before anything can move funds. Visit StalkChain and run that first lookup on a wallet you already watch.