> ## Documentation Index
> Fetch the complete documentation index at: https://docs.1tx.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# Instruments

> One identifier for every lending position, on every supported chain

## What an instrument is

An **instrument** is one place to earn yield: a protocol, an asset, on a chain.

| Component | Description            | Example                                    |
| --------- | ---------------------- | ------------------------------------------ |
| Protocol  | Where the deposit goes | Aave V3, Compound V3, Morpho, Euler, Fluid |
| Asset     | What is deposited      | USDC, EURC, GHO, cbBTC                     |
| Chain     | Where it lives         | Base, Arbitrum, Unichain, Monad            |

Aave USDC on Base is one instrument. Compound USDC on Base is a different one — same asset,
different protocol. Aave USDC on Arbitrum is a third.

## The identifier

Each instrument has a 32-byte id, computed deterministically:

```
instrumentId = (chainId << 224) | (keccak256(abi.encode(executionAddress, marketId)) >> 32)
```

```
0x00002105 c053a3e1290845e12a3eea14926472ce7f15da324cdf0700056fc04b
  ├──────┘ └──────────────────────────────────────────────────────┘
  chain id            keccak(executionAddress, marketId), truncated
  8453 = Base
```

* **`executionAddress`** is the contract the position lives in: the Aave Pool, the Comet market,
  or the vault itself.
* **`marketId`** distinguishes markets inside one contract. For per-asset protocols such as Aave
  and Compound it is `keccak256(abi.encode(underlying))`; for vault-based protocols — Morpho,
  Euler, Fluid — the vault *is* the market, so it is the vault address widened to 32 bytes.

Two consequences worth knowing:

<AccordionGroup>
  <Accordion title="The chain is readable from the id">
    The top four bytes are the chain id. `0x00002105…` is Base (8453), `0x0000a4b1…` Arbitrum (42161),
    `0x00000082…` Unichain (130). Nothing needs to be looked up to know where an instrument lives —
    which is why the calldata endpoint takes no `chainId` parameter.
  </Accordion>

  <Accordion title="The id is derived, not assigned">
    It falls out of facts that are already on chain. Two systems computing it from the same market get
    the same id, no registry consulted, no allocation step, no authority handing out numbers. Listing a
    market is a catalogue entry, not a transaction.
  </Accordion>
</AccordionGroup>

## What a row carries

Beyond identity, each instrument carries what you need to decide and to execute:

* **Tokens** — underlying and yield token, with their addresses, symbols and decimals.
* **Yield and size** — `currentApy`, `tvl`, and the reward breakdown behind them.
* **History** — snapshots and metrics; optionally the derived fields `coefficientOfVariation`,
  `historyDays`, `rewardSharePct` and `tier`, which rank instruments on yield that has held up
  rather than on today's headline number.
* **A recipe** — the protocol shape (`erc4626`, `aave-v3`, `comet`) that tells the calldata builder
  how this position is entered and exited. A row without one is readable but not executable.

<Tip>
  Sorting the catalogue by raw APY puts short-lived incentive spikes on top. `enrich=true` with
  `maxCv`, `minHistoryDays` or `tier=Core` is the honest ranking.
</Tip>

## Adding an instrument

Listing a market takes no contract deployment, no registration transaction and no upgrade: the
instrument becomes a row with its recipe, and a non-USDC underlying also needs its swap route
pinned. That is the whole unit of work — which is why the catalogue can track new markets as fast
as they appear rather than as fast as a deployment cycle allows.

## Next steps

<CardGroup cols={2}>
  <Card title="Instruments API" icon="code" href="/api-reference/endpoints/instruments">
    Filtering, enrichment and the full row shape
  </Card>

  <Card title="Atomic Bundles" icon="bolt" href="/concepts/atomic-bundles">
    Turning an instrument id into calls
  </Card>

  <Card title="Metrics API" icon="chart-line" href="/api-reference/endpoints/metrics">
    APY and TVL history per instrument
  </Card>

  <Card title="How It Works" icon="gears" href="/how-it-works">
    Recipes, swap legs and simulation
  </Card>
</CardGroup>