API reference, Bridges & wallets
Wallet PnL
- Elysium: Any wallet on Elysium: per token balance, cost basis, realized and unrealized PnL, with 1d / 7d / 30d / all totals and win rate.
- HyperEVM: Any wallet on HyperEVM: per token balance, cost basis, realized and unrealized PnL, with 1d / 7d / 30d / all totals and win rate.
- Not on HyperCore: HyperCore trades on its order book: an account's PnL is on its positions and fills (GET /v1/hypercore/wallet/{address}, /fills), its curve per hour or day with its account value at GET /v1/hypercore/wallet/{address}/pnl
GET https://api.femtos.xyz/v1/wallet/{address}/pnl
Parameters
| Param | In | Example or values | Meaning |
|---|---|---|---|
address | path | 0x876f1301aaa8452ceb98201cd4407fa9510a8181 (Elysium); 0x5a69a60ca8a4d189855b33bd9f1bbe71095c1039 (HyperEVM) | The wallet: 0x address, or a named wallet's handle |
layer | query | elysium (Elysium); hyperevm (HyperEVM) | EVM layer |
sort | query | (empty), value, pnl, realized, unrealized, volume, lastTrade | value (USD held), pnl, realized, unrealized, volume (USD bought + sold) or lastTrade: highest / newest first |
status | query | (empty), all, open, closed | all, open (held now) or closed |
pools | query | (empty), true | Each position with its pools (every swap of the token in each pool, priced or not) |
limit | query | 20 | Positions per page |
cursor | query | (optional) | Next page: `next_cursor` of the previous answer |
Example
Elysium
curl -H "Authorization: Bearer $FEMTOS_KEY" "https://api.femtos.xyz/v1/wallet/0x876f1301aaa8452ceb98201cd4407fa9510a8181/pnl?layer=elysium&sort=value&limit=20"HyperEVM
curl -H "Authorization: Bearer $FEMTOS_KEY" "https://api.femtos.xyz/v1/wallet/0x5a69a60ca8a4d189855b33bd9f1bbe71095c1039/pnl?layer=hyperevm&sort=value&limit=20"Key: Authorization: Bearer $FEMTOS_KEY. Get a free key, or with no browser through agent onboarding.
Response fields
| Field | Type | Meaning |
|---|---|---|
totals | object | Totals over every position of the wallet (not only the page): the last 24, 168, 720 UTC hours (1d, 7d, 30d) and all: {1d, 7d, 30d, all} |
positions[] | object | The page, by `sort` (highest first, null last; ties: last trade, then token): {token, symbol, name, decimals, spam, spamReason, held, heldNative, heldWithCost, heldNoCost, priceUsd, valueUsd, …} |
positions[].held | decimal | Balance at the indexed head (0: none), as /v1/balances reads it; the wrapped HYPE row: wrapped + native |
positions[].heldWithCost | decimal | min(held, max(bought − sold, 0)): the part of the balance bought in priced swaps |
positions[].costOfHeldUsd | decimal | heldWithCost × avgCostUsd, USD |
positions[].avgCostUsd | decimal | null | buyUsd / bought: the average cost; null without buys |
positions[].realizedPnlUsd | decimal | min(bought, sold) × (avgSellUsd − avgCostUsd); 0 without buys or sells, USD |
positions[].unrealizedPnlUsd | decimal | null | heldWithCost × priceUsd − costOfHeldUsd, USD; 0 when nothing is held with a cost; null when it is and the token has no price |
positions[].closed | boolean | A closed position (see the route): opened by a buy, then sold ≥ 99 % of bought or held ≤ 1 % of bought |
complete | boolean | false: the history was cut (see `from`), or pools=true listed the most pools |
next_cursor | string | null | Opaque cursor of the next page: pass it as `cursor`, unchanged. null on the last page |
billing | medium | medium |
Next page: cursor = the next_cursor of the previous answer, the same on every list (pagination).
Related: Bridges & wallets
- Cross-layer wallet GET /v1/wallet/{address} Elysium, HyperCore, HyperEVM
One address (or a named wallet's handle) on HyperCore, HyperEVM and Elysium, plus its latest events. - Wallet stream WS wallet Elysium, HyperCore, HyperEVM
Every event of the three layers touching one address. - Wallet list stream WS wallets Elysium, HyperCore, HyperEVM
Every event of the three layers touching any of up to 100 addresses, in one subscription, each event tagged with its address. - HyperCore account GET /v1/hypercore/wallet/{address} HyperCore
One address's HyperCore account: perp value and margin, positions, spot balances. - Wallet open orders GET /v1/hypercore/wallet/{address}/orders HyperCore
One wallet's open orders: resting limit orders and trigger orders, on the main dex and every HIP-3 dex. - Wallet order history GET /v1/hypercore/wallet/{address}/orders/history HyperCore
One wallet's orders that left the book, newest first: how (filled, canceled, rejected) and why, the size filled and its average price. - Wallet fills GET /v1/hypercore/wallet/{address}/fills HyperCore
One wallet's HyperCore fills, newest first, with closed PnL, fees and the position before each. - Wallet fills per bar GET /v1/hypercore/wallet/{address}/fills/bars HyperCore
One wallet's fills on one market summed per bar: buys and sells with their average price, and the position after each bar. - Wallet funding GET /v1/hypercore/wallet/{address}/funding HyperCore
One wallet's funding payments, newest first: paid or received per perp and hour, with the position and the rate. - Swaps by wallet GET /v1/trades Elysium, HyperEVM
Every swap a wallet sent (or a pool’s, a token’s), newest first, filterable by token, side, size and time. - Transfers by wallet GET /v1/transfers Elysium, HyperEVM
ERC-20 transfers sent and received by a wallet, newest first, filterable by token, direction, size and time. - Portfolio value history GET /v1/wallet/{address}/value Elysium, HyperEVM
Any address on HyperEVM: its total USD value per 5 min (1d), hour (7d) or day (30d, all). - Wallet PnL curve GET /v1/hypercore/wallet/{address}/pnl HyperCore
One HyperCore wallet's PnL per hour or day: realized, fees, funding, net and cumulative, and its account value. - Wallet PnL stream WS pnl Elysium, HyperEVM
A wallet's positions and PnL on HyperEVM (GET /v1/wallet/{address}/pnl), pushed on subscribe, then the positions each block changes. - Was I sandwiched? GET /v1/wallet/{address}/mev Elysium
Every sandwich of a wallet’s swaps on Elysium: the bot, its two transactions, what the wallet lost. Free, no key. - Ledger stream WS hc.ledger HyperCore
Deposits, withdrawals, transfers and other non-trade balance moves. - Bridge movements GET /v1/bridges Elysium, HyperCore, HyperEVM
Matched HyperCore ↔ HyperEVM transfers with 24 h stats. - Bridge stream WS elysium.bridge | bridge.transfers Elysium, HyperCore, HyperEVM
Each HyperCore ↔ HyperEVM transfer, initiated then completed. - Bridge movements stream WS bridges.recent Elysium, HyperCore, HyperEVM
The GET /v1/bridges answer (movements newest first, 24 h stats), pushed on subscribe, then when a movement of the route changes state. - Bridge coverage GET /v1/bridges/coverage HyperCore, HyperEVM
Every HyperCore ↔ HyperEVM leg since our data starts, paired with its other leg: matched share per direction and token, why the others are not, latency.
More
- This page as Markdown
- The whole API reference
- What Elysium serves
- What HyperEVM serves
- The whole API in one Markdown file
- OpenAPI 3.1 document
Agent guide (agents.md)llms.txtOpenAPIMCP serverGet an API keyChangelog