# How It Works

***

## How the Enterprise API Service Works

Yecho's service runs as a delegated backend for your dApp, computing and storing user-specific yield data on-chain. Here's the step-by-step process:

#### 1. User Address Discovery

To start tracking, Yecho needs the addresses of users interacting with your products (e.g., holders of your tokens or positions in your smart contracts). We offer two main options (both fully supported):

* **Option 1** : Provide us with user addresses via a secure write endpoint. This approach is optimal for privacy, user consent, and efficiency no unnecessary on-chain scans. Alternatively, you can provide a CSV export of holders. 
* **Option 2** (If public data): If your contracts are fully on-chain and public (e.g., via holders queries), Yecho can scan them periodically. This works well for smaller/static user bases, but increases RPC usage (higher costs). We can discuss during onboarding to choose the best fit for your setup.

#### 2. On-Chain Data Reading & Calculations

* Yecho queries your smart contracts on-chain to fetch user balances (e.g., positions in Aave, Morpho, etc.).
* If no prior balance is known: We record the initial snapshot.
* If a balance exists: We calculate the gain from the position (yield income) or cost from borrow since the last snapshot, using precise on-chain math.
* **Default Refresh Rate**: Once per day (customizable snapshot time, e.g., you can choose midnight UTC, 8 AM UTC, or any hour that suits your users/timezone).
* **Customizable**: Upgrade to higher frequencies (e.g., hourly or every 6h) for real-time updates throughout the day. This ensures users see intra-day changes, but increases RPC usage and pricing.

All data is stored securely in our backend (encrypted, compliant storage).

#### 3. Data Retrieval via Endpoint

Once calculated, integrate directly into your frontend:

**User Income Endpoint**:

* Call our endpoint: `GET https://api-XXX.yecho.app/api/users/{USER_ADDRESS}/income`
* Supports filters: `?chain=ethereum&token=USDC&start_date=2025-01-01&end_date=2025-12-31`\
  Returns full history of incomes.
* Response: JSON with full history:

```json
[
    {
        "daily_income": 0.04185007,
        "snapshot_date": "2025-12-28",
        "contract_id": 5,
        "blockchain": "Base",
        "asset": "GHO",
        "contract_type": "Lending"
    },
    {
        "daily_income": 0.324324,
        "snapshot_date": "2025-12-28",
        "contract_id": 618,
        "blockchain": "Base",
        "asset": "USDC",
        "contract_type": "Yield Aggregator"
    },
    {
        "daily_income": -0.124458,
        "snapshot_date": "2025-12-28",
        "contract_id": 915,
        "blockchain": "Base",
        "asset": "GHO",
        "contract_type": "Borrowing"
    }
]
```

**User Positions/Deposits Endpoint**:

Call our endpoint: `GET https://api-XXX.yecho.app/api/users/{USER_ADDRESS}/deposits`\
Supports similar filters: `?chain=ethereum&token=USDC`\
Returns known positions, balances tracked by Yecho.

```json
[
    {
        "contract_id": 1,
        "amount": 1000.54249,
        "updated_at": "2025-12-28",
        "blockchain": "Base",
        "asset": "USDC",
        "contract_type": "Lending"
    },
    {
        "contract_id": 5,
        "amount": 500.1790367,
        "updated_at": "2025-12-28",
        "blockchain": "Base",
        "asset": "GHO",
        "contract_type": "Lending"
    },
    {
        "contract_id": 7,
        "amount": 15600.1790367,
        "updated_at": "2025-12-28",
        "blockchain": "Ethereum",
        "asset": "GHO",
        "contract_type": "Staking"
    }
]
```

Easy to integrate into your frontend no extra logic needed.

#### Optional Dashboard Add-On

The core service is endpoint-only (plug-and-play for most dApps). However, if you want more visibility: We can deploy a simple admin dashboard showing:

* Timer to next snapshot
* Number of active users tracked
* Total yields generated by your users (aggregated anonymized)
* Usage stats (RPC calls, etc.)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.yecho.app/integrations/enterprise-and-api/how-it-works.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.