← Back to research

Crypto Wallet API: Endpoints, Data Models and Integration

Learn what a Crypto Wallet API returns, its core endpoints and data models, and how to pull holdings, balances and activity across chains.

By StalkchainPublished Nov 17, 2026Updated Nov 17, 202616 min read
crypto wallet apiwallet API endpointson-chain wallet data

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

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_id or account_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.

A three-step guide infographic explaining how to retrieve blockchain holdings and wallet activity via an API.

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.

  1. 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.

  2. Fetch balances per chain, and keep balance_raw beside decimals. 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.

  3. 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.

  4. Page transaction history by block or time range, and store the cursor. Example: a GET to the history resource with from_block and a page size, then the next call sends the cursor you saved. The slip is restarting at the newest page and double-counting transfers.

  5. Convert raw balances with token decimals, and attach price_source to 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.

  6. 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.

  7. Write observed_at on 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.

An infographic illustrating how different blockchain networks like Ethereum, Solana, and Bitcoin require unique wallet management strategies.

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.

A diagram outlining agent permissions and read-only boundaries for wallet intelligence and execution APIs in crypto.

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

A diagram illustrating a Wallet Data Hub connecting an account and credit balance to two access paths.

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.