> For the complete documentation index, see [llms.txt](https://docs.yifi.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.yifi.io/docs/earn/getting-started/how-it-works.md).

# How it works

The end-to-end YiFi Earn lifecycle – from discovering on-chain strategy to a live position and back out through withdrawal

A YiFi Earn integration moves through one loop: discover a strategy, execute a deposit, read the position, and – when the user is ready – withdraw. Everything below happens over the same normalized model, so the shape of a request doesn't change from one protocol to the next.

### The lifecycle at a glance

```mermaid
sequenceDiagram
    participant U as User wallet
    participant P as Partner app
    participant API as YiFi Core API
    participant R as Execution Layer (Portals / LI.FI)
    participant C as Underlying protocol

    P->>API: 1. Discover markets / strategies
    API-->>P: Normalized markets (rate, TVL, tokens)
    P->>API: 2. Zap quote (input token, amount, target market)
    API->>R: Resolve route
    R-->>API: Expected output, fees, steps
    API-->>P: Quote (expected receipt token, fee split)
    P->>API: 3. Zap build
    API-->>P: Ready-to-sign transaction payload
    P->>U: 4. Present transaction
    U->>C: 5. Sign & broadcast (from the user's own wallet)
    C-->>U: Receipt token (e.g. aToken)
    P->>API: 6. Track execution status
    API-->>P: Confirmed — position live
    P->>API: 7. Read portfolio (positions, history)
```

### The flow

{% stepper %}
{% step %}

#### Discover – the data layer

You query normalized **strategies** filtered by chain, platform, category, or token. Each strategy carries the fields you need to rank and display it – rate, TVL, participating tokens and detailed data that varies by strategy type. 

Under the hood this data is indexed with Subgraphs and Price Oracles.
{% endstep %}

{% step %}

#### Quote

`POST /zap/quote` with the input token, amount, and target market. The quote returns the expected output (the receipt token the user will hold), the fee breakdown, slippage tolerance, and the resolved route steps.
{% endstep %}

{% step %}

#### Build deposit transaction

`POST /zap/build` turns an accepted quote into a ready-to-sign transaction payload – context, the routing order, and the raw `tx`. This is a construction step only: YiFi assembles the **calldata**, it does not sign anything.
{% endstep %}

{% step %}

#### User signs the transaction

Once the transaction calldata is formed, it is passed to the user's wallet for signing. In our reference app, this is handled via Wagmi and Reown AppKit. 

YiFi never sees a private key, and no transaction executes without the user's explicit signature.
{% endstep %}

{% step %}

#### Settle into the protocol

Once broadcast, the transaction routes through the execution layer and deposits straight into the underlying protocol. The user receives the protocol's **own** receipt token directly. 
{% endstep %}

{% step %}

#### Track execution

`GET` the execution status to follow the transaction from broadcast to confirmation. Once confirmed, the position is live and readable through the Portfolio read-model.
{% endstep %}

{% step %}

#### Display position 

The Portfolio read-model returns **positions, performance, and transaction history by wallet address** – not just a balance snapshot. Performance is computed on a Weighted-Average Cost basis at the position level, calculated native-first with USD applied only at output, and gas is tracked separately in the chain's native asset.
{% endstep %}

{% step %}

#### Closing the position – withdraw

A withdrawal is the same lifecycle in reverse: **quote → build → sign → track**, against the position's receipt token. 
{% endstep %}
{% endstepper %}

### Where fees and attribution happen

The protocol-level fee is embedded in the zap and split **on-chain** through the FeeSplitter contract at execution time – there's no invoicing loop. Attribution is carried by the `X-Partner-Api-Key` header. See Fees structure and Partner attribution.