Femtos

Trades / swaps, and swap history of a wallet, pool or token

get_trades

Read-onlyIdempotent

Latest trades of a market, newest first. hypercore: fills of a coin (px, sz, side B = buyer aggressor / A, block time). hyperevm / elysium: DEX swaps of a pool (sender, amounts, px = pool price after the swap, USD value). Answer: an array of trades with only market / limit; one object {rows, next_cursor, coverage…} as soon as a history filter is given. History (hyperevm / elysium): pass trader (a wallet: every swap it sent), beneficiary (a wallet: every swap that paid it or took its tokens, smart-account swaps sent by a bundler included), pool or token (more than 20 pools: its priced swaps only, coverage: priced), optionally side, minUsd (USD at the swap), from / to (Unix ms): newest first, each row with its pool and symbols; filtered pages may hold fewer rows than limit, keep paging with next_cursor (null = no more).

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "get_trades"
  }
}

Input Schema

Name	Required	Description
`to`	No	Window end, Unix ms (exclusive)
`from`	No	Window start, Unix ms (inclusive)
`pool`	No	History of a pool (alias: market)
`side`	No	Buys or sells of the base
`layer`	No	Layer (default hypercore)
`limit`	No	Rows (default 50)
`token`	No	Swaps where this token is base or quote
`cursor`	No	Next page: `next_cursor` of the previous answer
`market`	No	Pair address (pool key) or coin; required without trader / beneficiary / pool / token
`minUsd`	No	Smallest USD value (the indexer's, at the swap)
`trader`	No	History of a wallet (tx.from of the swaps); a named wallet's handle works too
`network`	No	Elysium network: mainnet or testnet, same answers (testnet USD values null). HyperCore and HyperEVM are always mainnet (default mainnet)
`beneficiary`	No	History of a wallet as beneficiary: the swaps whose bought token it received or whose sold one it gave (a smart account's swaps sent by a bundler, a router paying out to it), and its own swaps that paid no other wallet; a named wallet's handle works too
`includeSpam`	No	Swaps of spam tokens too (flagged)

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedNov 8, 2026

addedInput schema / properties / beneficiary

Added value: +{
+  "description": "History of a wallet as beneficiary: the swaps whose bought token it received or whose sold one it gave (a smart account's swaps sent by a bundler, a router paying out to it), and its own swaps that paid no other wallet; a named wallet's handle works too",
+  "pattern": "^(0x[0-9a-fA-F]{40}|[A-Za-z0-9][A-Za-z0-9_.-]{0,63}\\.[0-9a-fA-F]{8,64})$",
+  "type": "string"
+}

changedInput schema / properties / market / description

Previous value: -"Pair address (pool key) or coin; required without trader / pool / token"New value: +"Pair address (pool key) or coin; required without trader / beneficiary / pool / token"

Changed1 schema field changedOct 30, 2026

addedInput schema / properties / network

Added value: +{
+  "description": "Elysium network: mainnet or testnet, same answers (testnet USD values null). HyperCore and HyperEVM are always mainnet (default mainnet)",
+  "enum": [
+    "mainnet",
+    "testnet"
+  ],
+  "type": "string"
+}

Changed28 schema fields changedOct 22, 2026

addedInput schema / properties / from / anyOf

Added value: +[
+  {
+    "maximum": 999999999999999,
+    "minimum": 0,
+    "type": "integer"
+  },
+  {
+    "pattern": "^\\d{1,15}$",
+    "type": "string"
+  }
+]

changedInput schema / properties / from / description

Previous value: -"History: window start, Unix ms"New value: +"Window start, Unix ms (inclusive)"

removedInput schema / properties / from / maximum
```
Removed value: -1000000000000000
```
removedInput schema / properties / from / minimum
```
Removed value: -0
```
removedInput schema / properties / from / type
```
Removed value: -"integer"
```

addedInput schema / properties / includeSpam

Added value: +{
+  "description": "Swaps of spam tokens too (flagged)",
+  "type": "boolean"
+}

changedInput schema / properties / layer / description

Previous value: -"Layer"New value: +"Layer (default hypercore)"

changedInput schema / properties / layer / enum

Previous value: -[
-  "hypercore",
-  "hyperevm",
-  "elysium"
-]New value: +[
+  "elysium",
+  "hyperevm",
+  "hypercore"
+]

changedInput schema / properties / limit / description

Previous value: -"Rows (default 50, max 500)"New value: +"Rows (default 50)"

changedInput schema / properties / limit / maximum
```
Previous value: -500New value: +1000
```

changedInput schema / properties / market / description

Previous value: -"hypercore: coin; hyperevm / elysium: pool key from list_markets (latest swaps of that pool)"New value: +"Pair address (pool key) or coin; required without trader / pool / token"

removedInput schema / properties / market / maxLength
```
Removed value: -160
```
removedInput schema / properties / market / minLength
```
Removed value: -1
```

addedInput schema / properties / minUsd / anyOf

Added value: +[
+  {
+    "minimum": 0,
+    "type": "number"
+  },
+  {
+    "pattern": "^\\d{1,15}(\\.\\d{1,6})?$",
+    "type": "string"
+  }
+]

changedInput schema / properties / minUsd / description

Previous value: -"History: smallest USD value"New value: +"Smallest USD value (the indexer's, at the swap)"

removedInput schema / properties / minUsd / minimum
```
Removed value: -0
```
removedInput schema / properties / minUsd / type
```
Removed value: -"number"
```

changedInput schema / properties / pool / description

Previous value: -"hyperevm / elysium: swap history of this pool"New value: +"History of a pool (alias: market)"

changedInput schema / properties / side / description

Previous value: -"History: buys or sells of the base"New value: +"Buys or sells of the base"

addedInput schema / properties / to / anyOf

Added value: +[
+  {
+    "maximum": 999999999999999,
+    "minimum": 0,
+    "type": "integer"
+  },
+  {
+    "pattern": "^\\d{1,15}$",
+    "type": "string"
+  }
+]

changedInput schema / properties / to / description

Previous value: -"History: window end, Unix ms (exclusive)"New value: +"Window end, Unix ms (exclusive)"

removedInput schema / properties / to / maximum
```
Removed value: -1000000000000000
```
removedInput schema / properties / to / minimum
```
Removed value: -0
```
removedInput schema / properties / to / type
```
Removed value: -"integer"
```

changedInput schema / properties / token / description

Previous value: -"hyperevm / elysium: swaps where this token is base or quote"New value: +"Swaps where this token is base or quote"

changedInput schema / properties / trader / description

Previous value: -"hyperevm / elysium: swap history of this wallet (tx.from)"New value: +"History of a wallet (tx.from of the swaps); a named wallet's handle works too"

changedInput schema / properties / trader / pattern

Previous value: -"^(0x[0-9a-fA-F]{40}|[a-z0-9][a-z0-9_.-]{0,63}\\.[0-9a-f]{8,64})$"New value: +"^(0x[0-9a-fA-F]{40}|[A-Za-z0-9][A-Za-z0-9_.-]{0,63}\\.[0-9a-fA-F]{8,64})$"

removedInput schema / required
```
Removed value: -[
-  "layer"
-]
```

Changed10 schema fields changedOct 22, 2026

addedInput schema / properties / cursor

Added value: +{
+  "description": "Next page: `next_cursor` of the previous answer",
+  "pattern": "^[A-Za-z0-9_-]{2,160}$",
+  "type": "string"
+}

addedInput schema / properties / from

Added value: +{
+  "description": "History: window start, Unix ms",
+  "maximum": 1000000000000000,
+  "minimum": 0,
+  "type": "integer"
+}

changedInput schema / properties / market / description

Previous value: -"hypercore: coin; hyperevm / elysium: pool key from list_markets"New value: +"hypercore: coin; hyperevm / elysium: pool key from list_markets (latest swaps of that pool)"

addedInput schema / properties / minUsd

Added value: +{
+  "description": "History: smallest USD value",
+  "minimum": 0,
+  "type": "number"
+}

addedInput schema / properties / pool

Added value: +{
+  "description": "hyperevm / elysium: swap history of this pool",
+  "pattern": "^0x[0-9a-fA-F]{40}(:0x[0-9a-fA-F]{64})?$",
+  "type": "string"
+}

addedInput schema / properties / side

Added value: +{
+  "description": "History: buys or sells of the base",
+  "enum": [
+    "buy",
+    "sell"
+  ],
+  "type": "string"
+}

addedInput schema / properties / to

Added value: +{
+  "description": "History: window end, Unix ms (exclusive)",
+  "maximum": 1000000000000000,
+  "minimum": 0,
+  "type": "integer"
+}

addedInput schema / properties / token

Added value: +{
+  "description": "hyperevm / elysium: swaps where this token is base or quote",
+  "pattern": "^0x[0-9a-fA-F]{40}$",
+  "type": "string"
+}

addedInput schema / properties / trader

Added value: +{
+  "description": "hyperevm / elysium: swap history of this wallet (tx.from)",
+  "pattern": "^(0x[0-9a-fA-F]{40}|[a-z0-9][a-z0-9_.-]{0,63}\\.[0-9a-f]{8,64})$",
+  "type": "string"
+}

changedInput schema / required

Previous value: -[
-  "layer",
-  "market"
-]New value: +[
+  "layer"
+]

First observedOct 21, 2026

TDQS

A3.9/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/openWorld=false, and the description adds real behavioral context beyond them: filtered pages may return fewer rows than limit, paging continues via next_cursor with null meaning exhausted, and token queries over 20 pools are restricted to `coverage: priced`. One residual gap: the 'coverage…' field's other values are never enumerated, and the testnet null-USD caveat is only implied via the network parameter.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core behavior, which is good, but the remainder is one dense paragraph of nested parentheticals and layer-specific asides that is hard to scan at speed. Every clause carries information, yet the absence of any structural separation (mode, filters, paging) costs readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 14-parameter, zero-required tool with no output schema, the description covers the two response shapes, pagination contract, filter interactions, and per-layer data differences. What is missing is modest: the enumeration of `coverage` values and the default limit (which the schema does supply).

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description earns above that by defining non-obvious semantics the schema only gestures at: px is the pool price after the swap, side B means buyer aggressor, minUsd is USD at the swap time, and beneficiary covers bundler-sent smart-account swaps and router payouts. The trader vs beneficiary distinction is the single most useful clarification here and is spelled out.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource ('Latest trades of a market, newest first') and then distinguishes per-layer semantics (hypercore fills with px/sz/aggressor vs hyperevm/elysium pool swaps with sender/amounts/USD). It never names adjacent siblings such as get_wallet_fills, get_builder_fills or get_twaps, so an agent must still infer the boundary from scope wording alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Clearly states the mode switch: array of trades when only market/limit is given, versus a {rows, next_cursor, coverage} object as soon as a history filter is supplied, and enumerates which filters exist (trader, beneficiary, pool, token, side, minUsd, from/to). It also gives the constraint that market is required absent trader/beneficiary/pool/token. It stops short of explicit when-to-use-this-instead-of-alternative guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Femtos tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?