# Income record

`hookr_income` is a read tool on the [MCP server](/docs/mcp). It answers what Hookr's contracts paid one revenue token, one wallet or one ERC-8004 agent on Robinhood Chain over the last 1 to 30 days: each payment with its transaction, summed by UTC day and currency. Every amount is a decimal string of raw units, and nothing in the answer is a price.

It reads Hookr's stored record of the contracts' own events, so a call scans no logs. A part that did not read is `unavailable` with a reason, never an empty list and never zero.

## Three ways to ask

Pass exactly one of `token`, `account` or `agentId`. `days` is 1 to 30, and 7 when left out.

| Argument | What it answers |
| --- | --- |
| `token` | A revenue token's door income. |
| `account` | What Hookr's pools paid a wallet: its claims and the trading fees its launch liquidity collected. `agent` says whether an Agent gate links the wallet to an ERC-8004 id, so you can ask again by that id. |
| `agentId` | The payments to the id's owner and to its agent wallet, and the door income of each revenue token the id's record lists under `revenueToken` that an Agent gate link confirms. |

An agent's record alone is a claim any agent can make about any token. A listed token counts only while the Agent gate links the token's creator or stream manager to the same id and that wallet is still the id's owner or agent wallet, the test `hookr_revenue_token` uses for its `agent`. A listed token that is not confirmed is named under `notCounted` with why.

## A revenue token's door income

Door income is counted as [Explorers and indexers](/docs/revenue-tokenizer/integrate-indexers#income-by-asset-and-by-door) counts it, per asset and per sync:

- add each door's `Forwarded(currency, amount)`;
- add the Rules' `Claimed` paid to the token, for the token itself or for one of its doors;
- take off the token's `LegPaid(door, asset, amount)`, Hookr's leg.

For ETH the sum has to equal the sync's own `pulledEth`. A token with a sync where it does not is not answered at all.

- Arbitrage recapture counts only through the family door's `Forwarded`. `RecaptureSplit`, `LpShareDonated`, `PoolAccrued` and a `Claimed` paid to the family door are never added on top.
- A failed pull counts nothing.
- A bonus and anything sent straight to the token are not income, so `IncomeRecognized` is not what is summed.
- A door's `Forwarded` in a transaction with no sync is not counted.
- Door income is counted before the sync's tip and Fee Bridge share and leaves out bonuses, so it is not the income figure `hookr_revenue_token` shows.

Revenue tokens minted before 29 October 2026 are counted by their own doors' events, on [the page for those tokens](/docs/previous-releases#reading-these-tokens).

## A wallet's lines

A wallet's lines are counted when paid, never when credited. A royalty, a King of the Pool prize or an arbitrage recapture share is first credited to the wallet in the pool's core and paid later by a claim, so counting both would count it twice.

| `source` | The event | What the line is |
| --- | --- | --- |
| `claim` | `Claimed(quote, beneficiary, to, amount)` from the Rules or a core, with the wallet as `beneficiary` | Everything that contract held for the wallet in one currency, wherever it was sent |
| `lp-fees` | `LPFeesCollected` from Hookr's launcher, with the wallet as `owner`, or as `recipient` where a family lock is the owner | The trading fees a launch position collected, one line for each of the pool's two currencies |

What a claim line can hold:

- The event names no pool and no kind, so a prize, a royalty, an integrator's rate and a Holder Pot payout read alike.
- For a wallet that also trades, it carries a partial fill's refund and the trader's own arbitrage recapture share, so its claims can be more than its income.
- A claim taken as PoolManager claims emits the same event as one paid in tokens.
- The line is counted for the wallet that earned it, the `beneficiary`, even when it was paid to another address.

A trading-fee line holds the pool's LP fee and any arbitrage recapture share donated to the position's range, as one amount. Fees collected while adding liquidity are taken off what the wallet adds, and fees delivered as PoolManager claims are not yet tokens; both are still a line.

Never counted, because each is a credit or a conversion that a `claim` line already pays: `PoolClaimed`, `PoolAccrued`, `IntegratorPaid`, `FeesAllocated`, `KingCrowned` and `ClaimsRedeemed`.

## What it does not cover

- Pools on a hook of your own: such a hook has its own core, which the record does not read.
- Trading fees of a Uniswap v4 position held outside Hookr's launcher.
- Anything not yet claimed or collected: `hookr_claims` reads what a wallet can claim now.
- A trading-fee line of a pool Hookr keeps off its lists and a line paid in a token Hookr does not list: each is named under `notCounted`.
- Days before the record starts. `window.recordStarts` says where it starts; when the days you ask reach back before it, `window.cut` is `true`, `window.from` is that start and `status` is `partial`.

## Ready, partial and unavailable

| `status` | Meaning |
| --- | --- |
| `ready` | Everything asked was read and counted. A day with no income rows is a counted nothing. |
| `partial` | Something was answered and something was left out: `notCounted` names each part with its token or transaction and the reason, or `window.cut` says the window starts later than asked. |
| `unavailable` | Nothing was answered, and `reason` says why. The answer carries no days, totals or lines. |

Read `unavailable` as not known, never as no income. The record answers `unavailable` while it is switched off, while it is behind the chain, and when a window holds more payments than one answer carries; ask for fewer days then.

`lines` lists the newest 200 payments and `linesOmitted` counts the rest. `days` and `totals` count every line, and the first and the last day of a window are part days. A currency's `symbol` and `decimals` are `null` where they did not read. Every address in an answer is lower case.

## A request and its answer

Put a revenue token's address in place of `0xYOUR_TOKEN`:

```
curl -s https://hookr.fun/api/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"hookr_income","arguments":{"token":"0xYOUR_TOKEN","days":1}}}'
```

The answer comes as `structuredContent`. This example, with made-up figures, shows its shape for a token whose doors delivered 0.0015 ETH in one sync:

```json
{
  "status": "ready",
  "subject": { "kind": "token", "token": "0xyour_token" },
  "window": { "days": 1, "from": 1794385670, "through": 1794472070, "throughBlock": "112383272", "recordStarts": 1792418719, "cut": false },
  "days": [
    { "date": "2026-11-11", "income": [] },
    { "date": "2026-11-12", "income": [{ "currency": "0x0000000000000000000000000000000000000000", "symbol": "ETH", "decimals": 18, "amount": "1500000000000000", "bySource": { "door": "1500000000000000" } }] }
  ],
  "totals": [{ "currency": "0x0000000000000000000000000000000000000000", "symbol": "ETH", "decimals": 18, "amount": "1500000000000000", "bySource": { "door": "1500000000000000" } }],
  "lines": [
    {
      "source": "door",
      "currency": "0x0000000000000000000000000000000000000000",
      "symbol": "ETH",
      "decimals": 18,
      "amount": "1500000000000000",
      "token": "0xyour_token",
      "txHash": "0x9f2c…41d7",
      "blockNumber": "112382972",
      "time": 1794471470,
      "explorer": "https://robin.etherscan.io/tx/0x9f2c…41d7"
    }
  ],
  "linesOmitted": 0,
  "notCounted": [],
  "rule": "Door income is what a revenue token's doors forwarded plus what the Rules paid into the token for it or its doors, less Hookr's leg, and a wallet's lines are payments made, never credits (https://hookr.fun/docs/integrations/income)."
}
```

Native ETH is the zero address. The tool is free and keyless, and a call counts against the same read budget as every other tool call.

---

This page: https://hookr.fun/docs/integrations/income. Every docs page as Markdown: https://hookr.fun/docs.md.
