> For the complete documentation index, see [llms.txt](https://docs.sierra.money/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sierra.money/building-with-sierra/api-integration.md).

# API Integration

### Overview

Learn how to access data for all vaults through Sierra's API.

The Sierra Protocol API returns the vault-level data, headline metrics (APY, TVL, exchange rate) and reserve allocations (what the vault is allocated to and in what amounts).

For the full endpoint reference, see the [Sierra API docs on SwaggerHub](https://app.swaggerhub.com/apis/OpenTrade/Sierra_api/6.27.0#/).

### Integration Paths

API integrations are read only. The Sierra Protocol API cannot deposit, withdraw or move funds, and it does not return account-level data.

To move money or read a wallet's balance, use Sierra's [web app](https://app.sierra.money/transparency) or the vault's smart contract (see [Smart Contract Integration](https://docs.sierra.money/building-with-sierra/smart-contract-integration.md) page).

### Authentication

API access requires an authentication token issued by Sierra Protocol on request (see Support section below). Pass it in the request header:

```
curl -X GET "https://api.sierra.money/<ENDPOINT_PATH>" \
  -H "x-api-key: <YOUR_API_TOKEN>"
```

**Note:** Keep your token secret. Do not put it in client-side code or public repositories.

### Pool address

Every endpoint below takes the Vault's pool address (i.e. SPLUS: 0x7706b1a531A7A8cB4c26D24CDc9ae4094a3e0302) as the lytPoolAddr path parameter. Always include it, so the response covers your desired vault only.

### Get Headline Vault Metrics

#### Return headline metrics for a vault

This endpoint returns the headline figures shown on each Vault's transparency tab. These are reported data points, not statements about future returns.

#### GET /lytHero/{lytPoolAddr}

| Parameter   | Type   | Required | Description                                                         |
| ----------- | ------ | -------- | ------------------------------------------------------------------- |
| lytPoolAddr | string | Yes      | The SPLUS pool address (0x7706b1a531A7A8cB4c26D24CDc9ae4094a3e0302) |

Example Request:

```
curl -X GET "https://api.sierra.money/lytHero/0x7706b1a531A7A8cB4c26D24CDc9ae4094a3e0302" \
  -H "x-api-key: <YOUR_API_TOKEN>"
```

Example Response:

```
{
  "action": "lytHeroHandler",
  "result": {
    "timestamp": 1767225600,
    "marketCap": 1000000.00,
    "volume24h": 0,
    "marketPrice": 0,
    "exchangeRate": 1.0100,
    "APY3Day": 0.0500,
    "APY7Day": 0.0500,
    "APY30Day": 0.0500,
    "APY30DaySimple": 0.0490
  }
}
```

#### Schema

The Response object:

| Field  | Type           | Title  | Description                                  |
| ------ | -------------- | ------ | -------------------------------------------- |
| action | string         | Action | Name of the handler that served the request. |
| result | HeroMetricsCTO | Result | The vault's headline metrics.                |

The HeroMetricsCTO object:

<table data-search="false"><thead><tr><th>Field</th><th>Type</th><th>Title</th><th>Description</th></tr></thead><tbody><tr><td>timestamp</td><td>integer</td><td>Timestamp</td><td>Unix time, in seconds, when the metrics were recorded.</td></tr><tr><td>marketCap</td><td>number</td><td>Market Cap</td><td>Market capitalization of the Vault.</td></tr><tr><td>volume24h</td><td>number</td><td>24h volume</td><td>Trading volume over the last 24 hours.</td></tr><tr><td>marketPrice</td><td>number</td><td>Market Price</td><td>Secondary-market price of the Vault token.</td></tr><tr><td>exchangeRate</td><td>number</td><td>Exchange Rate</td><td>The mint and redeem exchange rate in the token’s smart contract.</td></tr><tr><td>APY3Day</td><td>number</td><td>3-day APY</td><td>Average APY over the last 3 days, as a decimal (0.05 = 5%).</td></tr><tr><td>APY7Day</td><td>number</td><td>7-day APY</td><td>Average APY over the last 7 days, as a decimal.</td></tr><tr><td>APY30Day</td><td>number</td><td>30-day APY</td><td>Average APY over the last 30 days, as a decimal.</td></tr><tr><td>APY30DaySimple</td><td>number</td><td>30-day simple APY</td><td>30-day APY without compounding, as a decimal.</td></tr></tbody></table>

### Get Reserve Allocations

#### Return reserve allocations for the vault

This endpoint returns what the vault is allocated to and in what amounts, as shown on the transparency tab.

#### GET /lytPoolReservesState/{lytPoolAddr}

Example Request:

```
curl -X GET "https://api.sierra.money/lytPoolReservesState/0x7706b1a531A7A8cB4c26D24CDc9ae4094a3e0302" \
  -H "x-api-key: <YOUR_API_TOKEN>"
```

Example Response:

```
{
  "action": "lytReservePlanDataGetHandler",
  "result": {
    "lytPoolAddr": "0x7706b1a531A7A8cB4c26D24CDc9ae4094a3e0302",
    "lytPoolOverview": {
      "name": "Sierra OpenTrade Prime Plus Yield",
      "symbol": "SPLUS",
      "liquidityTokenSymbol": "USDC",
      "totalAssets": "10000000000000",
      "exchangeRate": "1010000000000000000"
    },
    "reserves": [
      {
        "apy": "0",
        "assetBalance": "20000000000",
        "assetBalanceMinusWithdrawals": "20000000000",
        "chainConfigurationName": "Ethereum",
        "chainId": 1,
        "currentPercentage": 0.2,
        "id": "00000000-0000-0000-0000-000000000001",
        "isLiquidityAsset": true,
        "lockedPendingExcess": "0",
        "poolAddr": "0x1111111111111111111111111111111111111111",
        "poolName": "USDC (ETH)",
        "poolToken": "USDC (ETH)",
        "stageName": "prod",
        "tokenBalance": "20000000000",
        "withdrawActivityCTOs": [],
        "yieldType": "LiquidityBuffer"
      },
      {
        "apy": "500",
        "assetBalance": "9980000000000",
        "assetBalanceMinusWithdrawals": "9980000000000",
        "chainConfigurationName": "Ethereum",
        "chainId": 1,
        "currentPercentage": 99.8,
        "id": "00000000-0000-0000-0000-000000000002",
        "isLiquidityAsset": false,
        "lockedPendingExcess": "0",
        "poolAddr": "0x2222222222222222222222222222222222222222",
        "poolName": "USDC Prime Plus Vault ETH",
        "poolToken": "xPPV-USDCEth",
        "stageName": "prod",
        "tokenBalance": "9880000000000",
        "withdrawActivityCTOs": [],
        "yieldType": "Prime Plus"
      }
    ],
    "totalReservesValue": "10000000000000",
    "yieldMetrics": {
      "date": "2026-01-01",
      "exchangeRate": 1.01,
      "marketCap": 10000000.00,
      "yield7DayTrailingAnnualized": 0.0500,
      "yield30DayTrailingAnnualized": 0.0500,
      "yield90DayTrailingAnnualized": null,
      "nullMetadata": {
        "yield90DayTrailing": "Vault is 60 days old; 90-day trailing yield requires at least 90 days since inception"
      }
    },
    "netAPY": "500",
    "timestamp": 1767225600000
  }
}
```

Note: The above values are illustrative.

#### Schema

The Response object:

| Field  | Type   | Title  | Description                                  |
| ------ | ------ | ------ | -------------------------------------------- |
| action | string | Action | Name of the handler that served the request. |
| result | object | Result | The vault's reserve data (see below).        |

The Result object:

| Field              | Type             | Title                | Description                                                                                                                      |
| ------------------ | ---------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| lytPoolAddr        | string           | Pool address         | Address of the vault queried.                                                                                                    |
| lytPoolOverview    | object           | Pool overview        | Vault configuration and on-chain state: name, symbol, liquidity token, total assets, exchange rate, fees and contract addresses. |
| reserves           | array of Reserve | Reserves             | One entry per reserve the vault can allocate to.                                                                                 |
| totalReservesValue | string           | Total reserves value | Value of all reserves, in liquidity-token base units.                                                                            |
| netAPY             | string           | Net APY              | Vault net APY, in basis points ("500" = 5.00%).                                                                                  |
| yieldMetrics       | object           | Yield metrics        | Trailing, year-to-date and since-inception yield figures.                                                                        |
| timestamp          | integer          | Timestamp            | Unix time, in milliseconds, when the response was built.                                                                         |

**The Reserve object**

<table><thead><tr><th width="278.27734375">Field</th><th>Type</th><th>Title</th><th>Description</th></tr></thead><tbody><tr><td>apy</td><td>string</td><td>APY</td><td>Current APY of the reserve, in basis points ("500" = 5.00%).</td></tr><tr><td>assetBalance</td><td>string</td><td>Asset balance</td><td>Value of the position, in liquidity-token base units (i.e. USDC).</td></tr><tr><td>assetBalanceMinusWithdrawals</td><td>string</td><td>Net asset balance</td><td>Asset balance net of pending withdrawals.</td></tr><tr><td>chainConfigurationName</td><td>string</td><td>Chain</td><td>Chain the reserve is held on, e.g. Ethereum, Avalanche, Plume.</td></tr><tr><td>chainId</td><td>integer</td><td>Chain ID</td><td>EVM chain ID.</td></tr><tr><td>currentPercentage</td><td>number</td><td>Current allocation</td><td>Share of total reserves, in percent (32.5 = 32.5%).</td></tr><tr><td>id</td><td>string</td><td>ID</td><td>Unique ID of the reserve.</td></tr><tr><td>isLiquidityAsset</td><td>boolean</td><td>Liquidity asset</td><td>true for uninvested liquidity-token balances (the liquidity buffer).</td></tr><tr><td>poolAddr</td><td>string</td><td>Reserve address</td><td>Address of the underlying vault or token.</td></tr><tr><td>poolName</td><td>string</td><td>Reserve name</td><td>Display name of the reserve.</td></tr><tr><td>poolToken</td><td>string</td><td>Reserve token</td><td>Token held for the reserve.</td></tr><tr><td>stageName</td><td>string</td><td>Stage</td><td>Deployment stage, prod in production.</td></tr><tr><td>tokenBalance</td><td>string</td><td>Token balance</td><td>Balance of poolToken held, in its base units.</td></tr><tr><td>withdrawActivityCTOs</td><td>array</td><td>Withdrawal activity</td><td>Pending withdrawal activity. Not returned for every reserve.</td></tr><tr><td>yieldType</td><td>string</td><td>Yield type</td><td>Reserve category, e.g. LiquidityBuffer, Prime Plus, DeFi or RWA.</td></tr></tbody></table>

Note: Token amounts are strings in the token's base units (USDC has 6 decimals, so "1000000" = 1 USDC).

### Support

* **Request Sierra API access:** <partnerships@sierra.money>&#x20;
* **Integration questions:** <partnerships@sierra.money>
* **Further documentation:** <https://docs.sierra.money>&#x20;

Note: Never send your API token by email or chat.
