# Cross-layer wallet · API reference · Femtos

> One address (or a named wallet's handle) on HyperCore, HyperEVM and Elysium, plus its latest events. GET /v1/wallet/{address} on Elysium, HyperCore and HyperEVM: parameters, response fields and a live call per layer.

- Base URL: `https://api.femtos.xyz/v1` (REST) · `wss://api.femtos.xyz/v1/ws` (WebSocket) · MCP: `https://api.femtos.xyz/mcp`
- Auth: `Authorization: Bearer $FEMTOS_KEY`. Free key: https://femtos.xyz/account/new (browser), or with
  no browser: `GET https://femtos.xyz/accounts/agent/challenge`, solve its proof of work, then `POST https://femtos.xyz/accounts/agent/signup`
  (https://femtos.xyz/agents.md#agent-onboarding)
- Decimals are exact strings, times Unix milliseconds, addresses lowercase `0x`
- Whole API in one file: https://femtos.xyz/agents.md · OpenAPI: https://api.femtos.xyz/v1/openapi.json · Index: https://femtos.xyz/llms.txt
- Page with live calls: https://femtos.xyz/reference/wallet

## Cross-layer wallet — GET `/v1/wallet/{address}`

One address (or a named wallet's handle) on HyperCore, HyperEVM and Elysium, plus its latest events.

Layers: Elysium, HyperCore, HyperEVM.
Page with live calls: https://femtos.xyz/reference/wallet?layer=<elysium|hypercore|hyperevm>

| Param | In | Example or values | Meaning |
|---|---|---|---|
| `address` | path | `<creator>` (Elysium); `<address>` (HyperCore); `<owner>` (HyperEVM) | 0x address, or a named wallet's handle <entityId>.<hex> |
| `includeSpam` | query | `(empty)`, `true` | Show spam tokens (tokens.spam: homoglyph, impostor, fake transfers…), flagged spam / spamReason; hidden from lists and USD totals by default (HyperEVM) |

Elysium:

```bash
curl -H "Authorization: Bearer $FEMTOS_KEY" "https://api.femtos.xyz/v1/wallet/<creator>"
```

HyperCore:

```bash
curl -H "Authorization: Bearer $FEMTOS_KEY" "https://api.femtos.xyz/v1/wallet/<address>"
```

HyperEVM:

```bash
curl -H "Authorization: Bearer $FEMTOS_KEY" "https://api.femtos.xyz/v1/wallet/<owner>"
```

| Field | Type | Meaning |
|---|---|---|
| `hypercore` | object | {perp:{accountValue, positions[]}, dexes[], spot:{balances[], totalUsd}, freshness:{source: info-server, asOf, latencyMs, state, head, headTime, lagMs}} or {unavailable}: live state from the node info server; head = the HyperCore block of the fills ingested |
| `hyperevm` | object | {balances:[{token, symbol, name, decimals, amount, priceUsd, usd, spam, spamReason, family?}], count, totalUsd, totalUsdComplete, includeSpam, spamHidden, height, asOf, syncing?, dataUntil?, nfts, activity, freshness, bridges:[core_evm rows]}: token balances at the indexed head (token-family tokens at balanceOf from their formula), USD at the pool prices of the last daily close; {balances:{unavailable}} when the database cannot answer. nfts: {erc721, erc1155, capped, collections[≤20]:{address, name, symbol, erc721, erc1155}, tokens[≤20]}. activity: {scope: EvmScope, swaps, transfers, more} (the moves are in `recent`). freshness: the layer as /api/status gives it {state, head, headTime, lagMs, chainHead?, blocksBehind?, behindMs?, clock?} |
| `elysium` | object | {balances:[{token, symbol, name, decimals, amount, priceUsd, usd, spam, spamReason, testnet}], count, totalUsd, includeSpam, spamHidden, testnet, nfts, activity, freshness, bridges:[evm_elysium rows]} (same nfts / activity / freshness as hyperevm) |
| `bridges` | object | The legs linking the layers over 7 days: {window: 7d, legs:{core_evm, evm_elysium}, inFlight:[{route, direction, status, detail?, token, amount, amountRaw?, t, ageMs, tx}] (core_evm initiated / stuck, evm_elysium sent / claimable), journeys:[{journey: core_to_elysium \| elysium_to_core, link: same_tx \| unique \| ordered, status: complete \| failed \| stuck \| in_flight, token (HyperEVM address, 0x2222…2222 = HYPE), amountRaw, startTime, endTime, evmMs, totalMs, hop1, hop2}]}: a journey = a hop into HyperEVM then a hop out of it of the same asset and amount by the same HyperEVM account within the hour (rules of the bridge_journeys view) |
| `recent[]` | object | 50 latest events of the three layers, newest first: {layer, kind, t, data} |
| `labels.<key>` | object | {address: name} of known addresses in the answer (bridge system senders, contracts) (Elysium, HyperCore) |
| `billing` | heavy | heavy |

## Related (Bridges & wallets)

- [Wallet stream](https://femtos.xyz/reference/ws/wallet.md) `WS wallet`: Every event of the three layers touching one address. (Elysium, HyperCore, HyperEVM)
- [Swaps by wallet](https://femtos.xyz/reference/wallet-trades.md) `GET /v1/trades`: Every swap a wallet sent (or a pool’s, a token’s), newest first, filterable by token, side, size and time. (Elysium, HyperEVM)
- [Transfers by wallet](https://femtos.xyz/reference/wallet-transfers.md) `GET /v1/transfers`: ERC-20 transfers sent and received by a wallet, newest first, filterable by token, direction, size and time. (Elysium, HyperEVM)
- [Ledger stream](https://femtos.xyz/reference/ws/ledger.md) `WS hc.ledger`: Deposits, withdrawals, transfers and other non-trade balance moves. (HyperCore)
- [Bridge movements](https://femtos.xyz/reference/bridge.md) `GET /v1/bridges`: Matched HyperCore ↔ HyperEVM transfers with 24 h stats. (Elysium, HyperCore, HyperEVM)
- [Bridge stream](https://femtos.xyz/reference/ws/bridge.md) `WS elysium.bridge · bridge.transfers`: Each HyperCore ↔ HyperEVM transfer, initiated then completed. (Elysium, HyperCore, HyperEVM)
- [Bridge coverage](https://femtos.xyz/reference/bridge-coverage.md) `GET /v1/bridges/coverage`: 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. (HyperCore, HyperEVM)

Every page: https://femtos.xyz/reference.md