# Earn

Vaults that earn yield from assets deposited on Tempo.

## List Earn vaults

`GET /v1/earn/vaults`

Lists compatible Earn vaults discovered from deployment events and resolved from current chain state.

### Query parameters

- `asset` `string`: Only include vaults accepting this asset address.
- `capability` `string[]`: Comma-separated capabilities that every returned vault must support.
- `chainId` `string | number`: Which Tempo network to query. Use the alias `mainnet` or `testnet`, or a numeric chain id. Defaults to `mainnet` when omitted.
- `cursor` `string`: Opaque keyset cursor from a previous response (`nextCursor`); pass it back verbatim to fetch the next page. Omit for the first (head) page.
- `engine.type` `string`: Only include vaults with this inferred engine type.
- `include` `string[]`: Comma-separated vault fields to include, such as `apy,tvl`.
- `limit` `integer`: How many items to return per page (5–200, default 10).
- `apy.window` `string`: Rate measurement window. Selecting a window includes `apy`, which measures `7d` on its own.

### Responses

#### `200`: A page of compatible deployed Earn vaults.

Headers:

- `RateLimit-Limit` `integer`: How many requests you may make in the current time window. Not sent on cached responses or `402` payment challenges.
- `RateLimit-Remaining` `integer`: How many requests you have left in the current window before you are rate-limited. Not sent on cached responses or `402` payment challenges.
- `RateLimit-Reset` `integer`: When the current window resets, as a Unix timestamp in seconds. Not sent on cached responses or `402` payment challenges.
- `RateLimit-Scope` `string`: Which quota this request counted against (e.g. `data:read`). Not sent on cached responses or `402` payment challenges.
- `tempo-request-id` `string`: A unique id for this request, returned on every response (and as `requestId` in error bodies). Include it when contacting support so we can find your request.

Body (`application/json`):

- `data` `object[]` _(required)_: Compatible deployed Earn vaults in deployment order.
  - `access` `object`: Vault share-token access, when requested.
    - `status` `string` _(required)_: Vault share-token access status.
  - `apy` `object`: Annualized share-price growth over the selected window, when requested via `include=apy` or by selecting `apy.window`. Null when the rate could not be measured: the vault predates the window, a boundary or historical quote is unavailable, the engine changed inside the window, or the growth is too extreme to annualize as a ratio.
    - `asOf` `string <date-time>` _(required)_: UTC instant the rate was measured to, rounded to a 15-minute bucket.
    - `methodology` `string` _(required)_: Identifier of the calculation that produced this rate.
    - `net` `string` _(required)_: Annualized fee-aware share-price growth, as a decimal ratio.
    - `window` `string` _(required)_: Window this rate covers.
  - `assetToken` `object` _(required)_: Asset accepted by the vault.
    - `address` `string` _(required)_: The TIP-20 token contract address on Tempo.
    - `currency` `string` _(required)_: The currency label for this token, such as `USD` for USD-denominated stablecoins.
    - `decimals` `integer` _(required)_: The number of decimal places the token uses; Tempo stablecoins typically use 6.
    - `id` `string` _(required)_: A stable resource ID for this token, equal to its contract address.
    - `logoUri` `string`: A URL for the token’s logo image, when one is available.
    - `name` `string` _(required)_: The token’s human-readable name.
    - `symbol` `string` _(required)_: The short ticker symbol wallets and apps show for this token.
    - `verified` `boolean` _(required)_: Whether this token is in Tempo’s curated verified token list.
  - `capabilities` `object`: Vault capabilities, when requested.
    - `asyncRedeem` `boolean` _(required)_: Whether queued redemptions are supported.
    - `boundedRedeem` `boolean` _(required)_: Whether redemption accepts a minimum asset bound.
    - `deposit` `boolean` _(required)_: Whether asset deposits are supported.
    - `exactWithdraw` `boolean` _(required)_: Whether exact asset withdrawals are supported.
    - `inKindDeposit` `boolean` _(required)_: Whether venue-share deposits are supported.
    - `privateRouting` `boolean` _(required)_: Whether private routing is supported.
    - `redeem` `boolean` _(required)_: Whether immediate redemptions are supported.
    - `routerSwaps` `boolean` _(required)_: Whether router token swaps are supported.
  - `description` `string` _(required)_: Curated vault description, or null when the vault is not verified.
  - `engine` `object` _(required)_: Current vault engine.
    - `address` `string` _(required)_: Current vault engine contract address.
    - `type` `string` _(required)_: Inferred engine type, or null when it is unknown.
    - `venue` `string` _(required)_: Yield venue, or null when the engine does not expose one.
  - `id` `string` _(required)_: Stable vault id, equal to the lowercase vault address.
  - `instantLiquidity` `string` _(required)_: Assets the venue would release right now, capped at the vault backing, in asset base units. Null when the engine interface cannot report a reliable number.
  - `label` `string` _(required)_: Vault display label.
  - `sharePrice` `object` _(required)_: Assets returned for one whole Earn share, in the asset display currency, or null when the engine cannot quote an exit.
    - `amount` `string` _(required)_: Value in base units at `decimals` precision.
    - `currency` `string` _(required)_: Display currency of this value.
    - `decimals` `integer` _(required)_: Decimal places used to convert `amount` into `formatted`.
    - `formatted` `string` _(required)_: Value rendered in whole units.
  - `shareToken` `object` _(required)_: Token representing vault shares.
    - `address` `string` _(required)_: The TIP-20 token contract address on Tempo.
    - `currency` `string` _(required)_: The currency label for this token, such as `USD` for USD-denominated stablecoins.
    - `decimals` `integer` _(required)_: The number of decimal places the token uses; Tempo stablecoins typically use 6.
    - `id` `string` _(required)_: A stable resource ID for this token, equal to its contract address.
    - `logoUri` `string`: A URL for the token’s logo image, when one is available.
    - `name` `string` _(required)_: The token’s human-readable name.
    - `symbol` `string` _(required)_: The short ticker symbol wallets and apps show for this token.
    - `verified` `boolean` _(required)_: Whether this token is in Tempo’s curated verified token list.
  - `slug` `string` _(required)_: Curated URL slug, or null when the vault is not verified.
  - `state` `object` _(required)_: Live vault accounting state.
    - `depositsPaused` `boolean` _(required)_: Whether new deposits are paused.
    - `engineShares` `string` _(required)_: Venue shares held for the vault.
    - `feesActive` `boolean` _(required)_: Whether fees are configured and not emergency-disabled.
    - `isAccountingAligned` `boolean` _(required)_: Whether Earn share supply matches its asset backing.
    - `openRedeemRequestCount` `integer` _(required)_: Queued redemptions still awaiting settlement.
    - `totalAssets` `string` _(required)_: Asset value of the active backing.
    - `totalEarnShares` `string` _(required)_: Active Earn share supply.
  - `tvl` `object`: Total assets valued in USD, when requested via `include=tvl`, or null when the asset has no priced display currency.
    - `amount` `string` _(required)_: Value in base units at `decimals` precision.
    - `currency` `string` _(required)_: Display currency of this value.
    - `decimals` `integer` _(required)_: Decimal places used to convert `amount` into `formatted`.
    - `formatted` `string` _(required)_: Value rendered in whole units.
  - `vaultAddress` `string` _(required)_: Earn vault contract address.
  - `verified` `boolean` _(required)_: Whether this vault is in the curated Earn registry.
  - `zone` `object`: Curated private Zone route, when requested, or null when absent.
    - `chainId` `string | number` _(required)_: Private Zone chain id.
    - `inputTokens` `string[]` _(required)_: Tokens accepted by private deposits.
    - `name` `string` _(required)_: Private Zone name.
    - `outputTokens` `string[]` _(required)_: Tokens supported by private redemptions.
- `meta` `object`: Rate provenance for valued fields.
  - `pricing` `object`: Rate provenance for valued fields. Present when `include=tvl` consulted conversion rates; absent when TVL was not requested, every value was identity-valued, or rates were unavailable.
    - `asOf` `string <date-time>` _(required)_: Publication date of the rate set as an ISO 8601 timestamp.
    - `basis` `string` _(required)_: Valuation basis: one token unit counts as one unit of its display currency.
    - `source` `string` _(required)_: FX rate oracle that supplied the conversion rates.
- `nextCursor` `string` _(required)_: Pass this back as the `cursor` query parameter to fetch the next page. `null` once you have reached the end of the list.

#### `400`: Invalid request.

Body (`application/json`):

- `error` `object` _(required)_: What went wrong.
  - `code` `string` _(required)_: A short, stable code you can branch on in your code (e.g. `token_not_found`).
  - `details` `object[]`: A list of specific problems, when the error is about your request (e.g. invalid fields).
    - `message` `string` _(required)_: A specific thing that went wrong, in plain language (e.g. why a field failed validation).
    - `path` `string | number[]`: Where the problem is, as a path into your request (e.g. `["query", "limit"]`). Present for validation errors.
  - `message` `string` _(required)_: A human-readable explanation of what went wrong.
- `requestId` `string` _(required)_: The id of this request — include it when contacting support.

#### `401`: Missing or invalid API key.

Body (`application/json`):

- `error` `object` _(required)_: What went wrong.
  - `code` `string` _(required)_: A short, stable code you can branch on in your code (e.g. `token_not_found`).
  - `details` `object[]`: A list of specific problems, when the error is about your request (e.g. invalid fields).
    - `message` `string` _(required)_: A specific thing that went wrong, in plain language (e.g. why a field failed validation).
    - `path` `string | number[]`: Where the problem is, as a path into your request (e.g. `["query", "limit"]`). Present for validation errors.
  - `message` `string` _(required)_: A human-readable explanation of what went wrong.
- `requestId` `string` _(required)_: The id of this request — include it when contacting support.

#### `402`: Payment required. This endpoint accepts MPP payment, and the request either exceeded free quota or needs a paid request credential. The challenge is protocol-native (handled by mppx), not the JSON error envelope: read the `WWW-Authenticate` header and retry with `Authorization: Payment <credential>`. A successful paid response carries `Payment-Receipt`.

Headers:

- `WWW-Authenticate` `string`: On a `402` response, the payment challenge to satisfy. Use it to build the `Authorization: Payment` credential and retry the request.

#### `429`: Rate limit exceeded. On endpoints that accept MPP, over-quota unpaid requests return `402 Payment Required` instead.

Headers:

- `RateLimit-Limit` `integer`: How many requests you may make in the current time window. Not sent on cached responses or `402` payment challenges.
- `RateLimit-Remaining` `integer`: How many requests you have left in the current window before you are rate-limited. Not sent on cached responses or `402` payment challenges.
- `RateLimit-Reset` `integer`: When the current window resets, as a Unix timestamp in seconds. Not sent on cached responses or `402` payment challenges.
- `RateLimit-Scope` `string`: Which quota this request counted against (e.g. `data:read`). Not sent on cached responses or `402` payment challenges.
- `tempo-request-id` `string`: A unique id for this request, returned on every response (and as `requestId` in error bodies). Include it when contacting support so we can find your request.
- `Retry-After` `integer`: How many seconds to wait before trying again. Sent with `429` (rate-limited) responses.

Body (`application/json`):

- `error` `object` _(required)_: What went wrong.
  - `code` `string` _(required)_: A short, stable code you can branch on in your code (e.g. `token_not_found`).
  - `details` `object[]`: A list of specific problems, when the error is about your request (e.g. invalid fields).
    - `message` `string` _(required)_: A specific thing that went wrong, in plain language (e.g. why a field failed validation).
    - `path` `string | number[]`: Where the problem is, as a path into your request (e.g. `["query", "limit"]`). Present for validation errors.
  - `message` `string` _(required)_: A human-readable explanation of what went wrong.
- `requestId` `string` _(required)_: The id of this request — include it when contacting support.

#### `500`: Internal server error.

Body (`application/json`):

- `error` `object` _(required)_: What went wrong.
  - `code` `string` _(required)_: A short, stable code you can branch on in your code (e.g. `token_not_found`).
  - `details` `object[]`: A list of specific problems, when the error is about your request (e.g. invalid fields).
    - `message` `string` _(required)_: A specific thing that went wrong, in plain language (e.g. why a field failed validation).
    - `path` `string | number[]`: Where the problem is, as a path into your request (e.g. `["query", "limit"]`). Present for validation errors.
  - `message` `string` _(required)_: A human-readable explanation of what went wrong.
- `requestId` `string` _(required)_: The id of this request — include it when contacting support.

#### `502`: Could not read Earn deployment or vault data.

Body (`application/json`):

- `error` `object` _(required)_: What went wrong.
  - `code` `string` _(required)_: A short, stable code you can branch on in your code (e.g. `token_not_found`).
  - `details` `object[]`: A list of specific problems, when the error is about your request (e.g. invalid fields).
    - `message` `string` _(required)_: A specific thing that went wrong, in plain language (e.g. why a field failed validation).
    - `path` `string | number[]`: Where the problem is, as a path into your request (e.g. `["query", "limit"]`). Present for validation errors.
  - `message` `string` _(required)_: A human-readable explanation of what went wrong.
- `requestId` `string` _(required)_: The id of this request — include it when contacting support.

### Example request

```bash
curl 'https://api.tempo.xyz/v1/earn/vaults?asset=0xbe058e1c4df8a4366a387bf595b284246a93039e&capability=asyncRedeem,boundedRedeem,deposit,exactWithdraw,inKindDeposit,privateRouting,redeem,routerSwaps&chainId=4217&cursor=WzIzNDU2Nzg5LDBd&engine.type=erc4626&include=access,apy,capabilities,token.logoUri,tvl,zone&limit=10&apy.window=7d'
```

```ts
fetch('https://api.tempo.xyz/v1/earn/vaults?asset=0xbe058e1c4df8a4366a387bf595b284246a93039e&capability=asyncRedeem,boundedRedeem,deposit,exactWithdraw,inKindDeposit,privateRouting,redeem,routerSwaps&chainId=4217&cursor=WzIzNDU2Nzg5LDBd&engine.type=erc4626&include=access,apy,capabilities,token.logoUri,tvl,zone&limit=10&apy.window=7d')
```

## List verified vaults

`GET /v1/earn/vaults/verified`

Lists registry-curated Earn vaults after resolving their current onchain configuration.

### Query parameters

- `asset` `string`: Only include vaults accepting this asset address.
- `capability` `string[]`: Comma-separated capabilities that every returned vault must support.
- `chainId` `string | number`: Which Tempo network to query. Use the alias `mainnet` or `testnet`, or a numeric chain id. Defaults to `mainnet` when omitted.
- `cursor` `string`: Opaque keyset cursor from a previous response (`nextCursor`); pass it back verbatim to fetch the next page. Omit for the first (head) page.
- `engine.type` `string`: Only include vaults with this inferred engine type.
- `include` `string[]`: Comma-separated vault fields to include, such as `apy,tvl`.
- `limit` `integer`: How many items to return per page (5–200, default 10).
- `apy.window` `string`: Rate measurement window. Selecting a window includes `apy`, which measures `7d` on its own.

### Responses

#### `200`: A page of registry-curated Earn vaults.

Headers:

- `RateLimit-Limit` `integer`: How many requests you may make in the current time window. Not sent on cached responses or `402` payment challenges.
- `RateLimit-Remaining` `integer`: How many requests you have left in the current window before you are rate-limited. Not sent on cached responses or `402` payment challenges.
- `RateLimit-Reset` `integer`: When the current window resets, as a Unix timestamp in seconds. Not sent on cached responses or `402` payment challenges.
- `RateLimit-Scope` `string`: Which quota this request counted against (e.g. `data:read`). Not sent on cached responses or `402` payment challenges.
- `tempo-request-id` `string`: A unique id for this request, returned on every response (and as `requestId` in error bodies). Include it when contacting support so we can find your request.

Body (`application/json`):

- `data` `object[]` _(required)_: Registry-curated Earn vaults ordered by vault address.
  - `access` `object`: Vault share-token access, when requested.
    - `status` `string` _(required)_: Vault share-token access status.
  - `apy` `object`: Annualized share-price growth over the selected window, when requested via `include=apy` or by selecting `apy.window`. Null when the rate could not be measured: the vault predates the window, a boundary or historical quote is unavailable, the engine changed inside the window, or the growth is too extreme to annualize as a ratio.
    - `asOf` `string <date-time>` _(required)_: UTC instant the rate was measured to, rounded to a 15-minute bucket.
    - `methodology` `string` _(required)_: Identifier of the calculation that produced this rate.
    - `net` `string` _(required)_: Annualized fee-aware share-price growth, as a decimal ratio.
    - `window` `string` _(required)_: Window this rate covers.
  - `assetToken` `object` _(required)_: Asset accepted by the vault.
    - `address` `string` _(required)_: The TIP-20 token contract address on Tempo.
    - `currency` `string` _(required)_: The currency label for this token, such as `USD` for USD-denominated stablecoins.
    - `decimals` `integer` _(required)_: The number of decimal places the token uses; Tempo stablecoins typically use 6.
    - `id` `string` _(required)_: A stable resource ID for this token, equal to its contract address.
    - `logoUri` `string`: A URL for the token’s logo image, when one is available.
    - `name` `string` _(required)_: The token’s human-readable name.
    - `symbol` `string` _(required)_: The short ticker symbol wallets and apps show for this token.
    - `verified` `boolean` _(required)_: Whether this token is in Tempo’s curated verified token list.
  - `capabilities` `object`: Vault capabilities, when requested.
    - `asyncRedeem` `boolean` _(required)_: Whether queued redemptions are supported.
    - `boundedRedeem` `boolean` _(required)_: Whether redemption accepts a minimum asset bound.
    - `deposit` `boolean` _(required)_: Whether asset deposits are supported.
    - `exactWithdraw` `boolean` _(required)_: Whether exact asset withdrawals are supported.
    - `inKindDeposit` `boolean` _(required)_: Whether venue-share deposits are supported.
    - `privateRouting` `boolean` _(required)_: Whether private routing is supported.
    - `redeem` `boolean` _(required)_: Whether immediate redemptions are supported.
    - `routerSwaps` `boolean` _(required)_: Whether router token swaps are supported.
  - `description` `string` _(required)_: Curated vault description, or null when the vault is not verified.
  - `engine` `object` _(required)_
    - `address` `string` _(required)_: Current vault engine contract address.
    - `type` `string` _(required)_: Inferred vault engine type.
    - `venue` `string` _(required)_: Yield venue, or null when the engine does not expose one.
  - `id` `string` _(required)_: Stable vault id, equal to the lowercase vault address.
  - `instantLiquidity` `string` _(required)_: Assets the venue would release right now, capped at the vault backing, in asset base units. Null when the engine interface cannot report a reliable number.
  - `label` `string` _(required)_: Vault display label.
  - `sharePrice` `object` _(required)_: Assets returned for one whole Earn share, in the asset display currency, or null when the engine cannot quote an exit.
    - `amount` `string` _(required)_: Value in base units at `decimals` precision.
    - `currency` `string` _(required)_: Display currency of this value.
    - `decimals` `integer` _(required)_: Decimal places used to convert `amount` into `formatted`.
    - `formatted` `string` _(required)_: Value rendered in whole units.
  - `shareToken` `object` _(required)_: Token representing vault shares.
    - `address` `string` _(required)_: The TIP-20 token contract address on Tempo.
    - `currency` `string` _(required)_: The currency label for this token, such as `USD` for USD-denominated stablecoins.
    - `decimals` `integer` _(required)_: The number of decimal places the token uses; Tempo stablecoins typically use 6.
    - `id` `string` _(required)_: A stable resource ID for this token, equal to its contract address.
    - `logoUri` `string`: A URL for the token’s logo image, when one is available.
    - `name` `string` _(required)_: The token’s human-readable name.
    - `symbol` `string` _(required)_: The short ticker symbol wallets and apps show for this token.
    - `verified` `boolean` _(required)_: Whether this token is in Tempo’s curated verified token list.
  - `slug` `string` _(required)_: Stable curated vault slug.
  - `state` `object` _(required)_: Live vault accounting state.
    - `depositsPaused` `boolean` _(required)_: Whether new deposits are paused.
    - `engineShares` `string` _(required)_: Venue shares held for the vault.
    - `feesActive` `boolean` _(required)_: Whether fees are configured and not emergency-disabled.
    - `isAccountingAligned` `boolean` _(required)_: Whether Earn share supply matches its asset backing.
    - `openRedeemRequestCount` `integer` _(required)_: Queued redemptions still awaiting settlement.
    - `totalAssets` `string` _(required)_: Asset value of the active backing.
    - `totalEarnShares` `string` _(required)_: Active Earn share supply.
  - `tvl` `object`: Total assets valued in USD, when requested via `include=tvl`, or null when the asset has no priced display currency.
    - `amount` `string` _(required)_: Value in base units at `decimals` precision.
    - `currency` `string` _(required)_: Display currency of this value.
    - `decimals` `integer` _(required)_: Decimal places used to convert `amount` into `formatted`.
    - `formatted` `string` _(required)_: Value rendered in whole units.
  - `vaultAddress` `string` _(required)_: Earn vault contract address.
  - `verified` `boolean` _(required)_: This vault is in the curated Earn registry.
  - `zone` `object`: Curated private Zone route, when requested, or null when absent.
    - `chainId` `string | number` _(required)_: Private Zone chain id.
    - `inputTokens` `string[]` _(required)_: Tokens accepted by private deposits.
    - `name` `string` _(required)_: Private Zone name.
    - `outputTokens` `string[]` _(required)_: Tokens supported by private redemptions.
- `meta` `object`: Rate provenance for valued fields.
  - `pricing` `object`: Rate provenance for valued fields. Present when `include=tvl` consulted conversion rates; absent when TVL was not requested, every value was identity-valued, or rates were unavailable.
    - `asOf` `string <date-time>` _(required)_: Publication date of the rate set as an ISO 8601 timestamp.
    - `basis` `string` _(required)_: Valuation basis: one token unit counts as one unit of its display currency.
    - `source` `string` _(required)_: FX rate oracle that supplied the conversion rates.
- `nextCursor` `string` _(required)_: Pass this back as the `cursor` query parameter to fetch the next page. `null` once you have reached the end of the list.

#### `400`: Invalid request.

Body (`application/json`):

- `error` `object` _(required)_: What went wrong.
  - `code` `string` _(required)_: A short, stable code you can branch on in your code (e.g. `token_not_found`).
  - `details` `object[]`: A list of specific problems, when the error is about your request (e.g. invalid fields).
    - `message` `string` _(required)_: A specific thing that went wrong, in plain language (e.g. why a field failed validation).
    - `path` `string | number[]`: Where the problem is, as a path into your request (e.g. `["query", "limit"]`). Present for validation errors.
  - `message` `string` _(required)_: A human-readable explanation of what went wrong.
- `requestId` `string` _(required)_: The id of this request — include it when contacting support.

#### `401`: Missing or invalid API key.

Body (`application/json`):

- `error` `object` _(required)_: What went wrong.
  - `code` `string` _(required)_: A short, stable code you can branch on in your code (e.g. `token_not_found`).
  - `details` `object[]`: A list of specific problems, when the error is about your request (e.g. invalid fields).
    - `message` `string` _(required)_: A specific thing that went wrong, in plain language (e.g. why a field failed validation).
    - `path` `string | number[]`: Where the problem is, as a path into your request (e.g. `["query", "limit"]`). Present for validation errors.
  - `message` `string` _(required)_: A human-readable explanation of what went wrong.
- `requestId` `string` _(required)_: The id of this request — include it when contacting support.

#### `402`: Payment required. This endpoint accepts MPP payment, and the request either exceeded free quota or needs a paid request credential. The challenge is protocol-native (handled by mppx), not the JSON error envelope: read the `WWW-Authenticate` header and retry with `Authorization: Payment <credential>`. A successful paid response carries `Payment-Receipt`.

Headers:

- `WWW-Authenticate` `string`: On a `402` response, the payment challenge to satisfy. Use it to build the `Authorization: Payment` credential and retry the request.

#### `429`: Rate limit exceeded. On endpoints that accept MPP, over-quota unpaid requests return `402 Payment Required` instead.

Headers:

- `RateLimit-Limit` `integer`: How many requests you may make in the current time window. Not sent on cached responses or `402` payment challenges.
- `RateLimit-Remaining` `integer`: How many requests you have left in the current window before you are rate-limited. Not sent on cached responses or `402` payment challenges.
- `RateLimit-Reset` `integer`: When the current window resets, as a Unix timestamp in seconds. Not sent on cached responses or `402` payment challenges.
- `RateLimit-Scope` `string`: Which quota this request counted against (e.g. `data:read`). Not sent on cached responses or `402` payment challenges.
- `tempo-request-id` `string`: A unique id for this request, returned on every response (and as `requestId` in error bodies). Include it when contacting support so we can find your request.
- `Retry-After` `integer`: How many seconds to wait before trying again. Sent with `429` (rate-limited) responses.

Body (`application/json`):

- `error` `object` _(required)_: What went wrong.
  - `code` `string` _(required)_: A short, stable code you can branch on in your code (e.g. `token_not_found`).
  - `details` `object[]`: A list of specific problems, when the error is about your request (e.g. invalid fields).
    - `message` `string` _(required)_: A specific thing that went wrong, in plain language (e.g. why a field failed validation).
    - `path` `string | number[]`: Where the problem is, as a path into your request (e.g. `["query", "limit"]`). Present for validation errors.
  - `message` `string` _(required)_: A human-readable explanation of what went wrong.
- `requestId` `string` _(required)_: The id of this request — include it when contacting support.

#### `500`: Internal server error.

Body (`application/json`):

- `error` `object` _(required)_: What went wrong.
  - `code` `string` _(required)_: A short, stable code you can branch on in your code (e.g. `token_not_found`).
  - `details` `object[]`: A list of specific problems, when the error is about your request (e.g. invalid fields).
    - `message` `string` _(required)_: A specific thing that went wrong, in plain language (e.g. why a field failed validation).
    - `path` `string | number[]`: Where the problem is, as a path into your request (e.g. `["query", "limit"]`). Present for validation errors.
  - `message` `string` _(required)_: A human-readable explanation of what went wrong.
- `requestId` `string` _(required)_: The id of this request — include it when contacting support.

#### `502`: Could not read curated Earn registry or vault data.

Body (`application/json`):

- `error` `object` _(required)_: What went wrong.
  - `code` `string` _(required)_: A short, stable code you can branch on in your code (e.g. `token_not_found`).
  - `details` `object[]`: A list of specific problems, when the error is about your request (e.g. invalid fields).
    - `message` `string` _(required)_: A specific thing that went wrong, in plain language (e.g. why a field failed validation).
    - `path` `string | number[]`: Where the problem is, as a path into your request (e.g. `["query", "limit"]`). Present for validation errors.
  - `message` `string` _(required)_: A human-readable explanation of what went wrong.
- `requestId` `string` _(required)_: The id of this request — include it when contacting support.

### Example request

```bash
curl 'https://api.tempo.xyz/v1/earn/vaults/verified?asset=0xbe058e1c4df8a4366a387bf595b284246a93039e&capability=asyncRedeem,boundedRedeem,deposit,exactWithdraw,inKindDeposit,privateRouting,redeem,routerSwaps&chainId=4217&cursor=WzIzNDU2Nzg5LDBd&engine.type=erc4626&include=access,apy,capabilities,token.logoUri,tvl,zone&limit=10&apy.window=7d'
```

```ts
fetch('https://api.tempo.xyz/v1/earn/vaults/verified?asset=0xbe058e1c4df8a4366a387bf595b284246a93039e&capability=asyncRedeem,boundedRedeem,deposit,exactWithdraw,inKindDeposit,privateRouting,redeem,routerSwaps&chainId=4217&cursor=WzIzNDU2Nzg5LDBd&engine.type=erc4626&include=access,apy,capabilities,token.logoUri,tvl,zone&limit=10&apy.window=7d')
```

## Get Earn vault

`GET /v1/earn/vaults/{vaultId}`

Resolves any compatible Earn vault directly from current chain state and enriches it when curated.

### Path parameters

- `vaultId` `string` _(required)_: Earn vault contract address.

### Query parameters

- `chainId` `string | number`: Which Tempo network to query. Use the alias `mainnet` or `testnet`, or a numeric chain id. Defaults to `mainnet` when omitted.
- `include` `string[]`: Comma-separated vault fields to include, such as `apy,tvl`.
- `apy.window` `string`: Rate measurement window. Selecting a window includes `apy`, which measures `7d` on its own.

### Responses

#### `200`: One compatible Earn vault.

Headers:

- `RateLimit-Limit` `integer`: How many requests you may make in the current time window. Not sent on cached responses or `402` payment challenges.
- `RateLimit-Remaining` `integer`: How many requests you have left in the current window before you are rate-limited. Not sent on cached responses or `402` payment challenges.
- `RateLimit-Reset` `integer`: When the current window resets, as a Unix timestamp in seconds. Not sent on cached responses or `402` payment challenges.
- `RateLimit-Scope` `string`: Which quota this request counted against (e.g. `data:read`). Not sent on cached responses or `402` payment challenges.
- `tempo-request-id` `string`: A unique id for this request, returned on every response (and as `requestId` in error bodies). Include it when contacting support so we can find your request.

Body (`application/json`):

- `access` `object`: Vault share-token access, when requested.
  - `status` `string` _(required)_: Vault share-token access status.
- `apy` `object`: Annualized share-price growth over the selected window, when requested via `include=apy` or by selecting `apy.window`. Null when the rate could not be measured: the vault predates the window, a boundary or historical quote is unavailable, the engine changed inside the window, or the growth is too extreme to annualize as a ratio.
  - `asOf` `string <date-time>` _(required)_: UTC instant the rate was measured to, rounded to a 15-minute bucket.
  - `methodology` `string` _(required)_: Identifier of the calculation that produced this rate.
  - `net` `string` _(required)_: Annualized fee-aware share-price growth, as a decimal ratio.
  - `window` `string` _(required)_: Window this rate covers.
- `assetToken` `object` _(required)_: Asset accepted by the vault.
  - `address` `string` _(required)_: The TIP-20 token contract address on Tempo.
  - `currency` `string` _(required)_: The currency label for this token, such as `USD` for USD-denominated stablecoins.
  - `decimals` `integer` _(required)_: The number of decimal places the token uses; Tempo stablecoins typically use 6.
  - `id` `string` _(required)_: A stable resource ID for this token, equal to its contract address.
  - `logoUri` `string`: A URL for the token’s logo image, when one is available.
  - `name` `string` _(required)_: The token’s human-readable name.
  - `symbol` `string` _(required)_: The short ticker symbol wallets and apps show for this token.
  - `verified` `boolean` _(required)_: Whether this token is in Tempo’s curated verified token list.
- `capabilities` `object`: Vault capabilities, when requested.
  - `asyncRedeem` `boolean` _(required)_: Whether queued redemptions are supported.
  - `boundedRedeem` `boolean` _(required)_: Whether redemption accepts a minimum asset bound.
  - `deposit` `boolean` _(required)_: Whether asset deposits are supported.
  - `exactWithdraw` `boolean` _(required)_: Whether exact asset withdrawals are supported.
  - `inKindDeposit` `boolean` _(required)_: Whether venue-share deposits are supported.
  - `privateRouting` `boolean` _(required)_: Whether private routing is supported.
  - `redeem` `boolean` _(required)_: Whether immediate redemptions are supported.
  - `routerSwaps` `boolean` _(required)_: Whether router token swaps are supported.
- `description` `string` _(required)_: Curated vault description, or null when the vault is not verified.
- `engine` `object` _(required)_: Current vault engine.
  - `address` `string` _(required)_: Current vault engine contract address.
  - `type` `string` _(required)_: Inferred engine type, or null when it is unknown.
  - `venue` `string` _(required)_: Yield venue, or null when the engine does not expose one.
- `id` `string` _(required)_: Stable vault id, equal to the lowercase vault address.
- `instantLiquidity` `string` _(required)_: Assets the venue would release right now, capped at the vault backing, in asset base units. Null when the engine interface cannot report a reliable number.
- `label` `string` _(required)_: Vault display label.
- `sharePrice` `object` _(required)_: Assets returned for one whole Earn share, in the asset display currency, or null when the engine cannot quote an exit.
  - `amount` `string` _(required)_: Value in base units at `decimals` precision.
  - `currency` `string` _(required)_: Display currency of this value.
  - `decimals` `integer` _(required)_: Decimal places used to convert `amount` into `formatted`.
  - `formatted` `string` _(required)_: Value rendered in whole units.
- `shareToken` `object` _(required)_: Token representing vault shares.
  - `address` `string` _(required)_: The TIP-20 token contract address on Tempo.
  - `currency` `string` _(required)_: The currency label for this token, such as `USD` for USD-denominated stablecoins.
  - `decimals` `integer` _(required)_: The number of decimal places the token uses; Tempo stablecoins typically use 6.
  - `id` `string` _(required)_: A stable resource ID for this token, equal to its contract address.
  - `logoUri` `string`: A URL for the token’s logo image, when one is available.
  - `name` `string` _(required)_: The token’s human-readable name.
  - `symbol` `string` _(required)_: The short ticker symbol wallets and apps show for this token.
  - `verified` `boolean` _(required)_: Whether this token is in Tempo’s curated verified token list.
- `slug` `string` _(required)_: Curated URL slug, or null when the vault is not verified.
- `state` `object` _(required)_: Live vault accounting state.
  - `depositsPaused` `boolean` _(required)_: Whether new deposits are paused.
  - `engineShares` `string` _(required)_: Venue shares held for the vault.
  - `feesActive` `boolean` _(required)_: Whether fees are configured and not emergency-disabled.
  - `isAccountingAligned` `boolean` _(required)_: Whether Earn share supply matches its asset backing.
  - `openRedeemRequestCount` `integer` _(required)_: Queued redemptions still awaiting settlement.
  - `totalAssets` `string` _(required)_: Asset value of the active backing.
  - `totalEarnShares` `string` _(required)_: Active Earn share supply.
- `tvl` `object`: Total assets valued in USD, when requested via `include=tvl`, or null when the asset has no priced display currency.
  - `amount` `string` _(required)_: Value in base units at `decimals` precision.
  - `currency` `string` _(required)_: Display currency of this value.
  - `decimals` `integer` _(required)_: Decimal places used to convert `amount` into `formatted`.
  - `formatted` `string` _(required)_: Value rendered in whole units.
- `vaultAddress` `string` _(required)_: Earn vault contract address.
- `verified` `boolean` _(required)_: Whether this vault is in the curated Earn registry.
- `zone` `object`: Curated private Zone route, when requested, or null when absent.
  - `chainId` `string | number` _(required)_: Private Zone chain id.
  - `inputTokens` `string[]` _(required)_: Tokens accepted by private deposits.
  - `name` `string` _(required)_: Private Zone name.
  - `outputTokens` `string[]` _(required)_: Tokens supported by private redemptions.
- `meta` `object`: Rate provenance for valued fields.
  - `pricing` `object`: Rate provenance for valued fields. Present when `include=tvl` consulted conversion rates; absent when TVL was not requested, every value was identity-valued, or rates were unavailable.
    - `asOf` `string <date-time>` _(required)_: Publication date of the rate set as an ISO 8601 timestamp.
    - `basis` `string` _(required)_: Valuation basis: one token unit counts as one unit of its display currency.
    - `source` `string` _(required)_: FX rate oracle that supplied the conversion rates.

#### `400`: Invalid request.

Body (`application/json`):

- `error` `object` _(required)_: What went wrong.
  - `code` `string` _(required)_: A short, stable code you can branch on in your code (e.g. `token_not_found`).
  - `details` `object[]`: A list of specific problems, when the error is about your request (e.g. invalid fields).
    - `message` `string` _(required)_: A specific thing that went wrong, in plain language (e.g. why a field failed validation).
    - `path` `string | number[]`: Where the problem is, as a path into your request (e.g. `["query", "limit"]`). Present for validation errors.
  - `message` `string` _(required)_: A human-readable explanation of what went wrong.
- `requestId` `string` _(required)_: The id of this request — include it when contacting support.

#### `401`: Missing or invalid API key.

Body (`application/json`):

- `error` `object` _(required)_: What went wrong.
  - `code` `string` _(required)_: A short, stable code you can branch on in your code (e.g. `token_not_found`).
  - `details` `object[]`: A list of specific problems, when the error is about your request (e.g. invalid fields).
    - `message` `string` _(required)_: A specific thing that went wrong, in plain language (e.g. why a field failed validation).
    - `path` `string | number[]`: Where the problem is, as a path into your request (e.g. `["query", "limit"]`). Present for validation errors.
  - `message` `string` _(required)_: A human-readable explanation of what went wrong.
- `requestId` `string` _(required)_: The id of this request — include it when contacting support.

#### `402`: Payment required. This endpoint accepts MPP payment, and the request either exceeded free quota or needs a paid request credential. The challenge is protocol-native (handled by mppx), not the JSON error envelope: read the `WWW-Authenticate` header and retry with `Authorization: Payment <credential>`. A successful paid response carries `Payment-Receipt`.

Headers:

- `WWW-Authenticate` `string`: On a `402` response, the payment challenge to satisfy. Use it to build the `Authorization: Payment` credential and retry the request.

#### `404`: No compatible Earn vault was found at this address.

Body (`application/json`):

- `error` `object` _(required)_: What went wrong.
  - `code` `string` _(required)_: A short, stable code you can branch on in your code (e.g. `token_not_found`).
  - `details` `object[]`: A list of specific problems, when the error is about your request (e.g. invalid fields).
    - `message` `string` _(required)_: A specific thing that went wrong, in plain language (e.g. why a field failed validation).
    - `path` `string | number[]`: Where the problem is, as a path into your request (e.g. `["query", "limit"]`). Present for validation errors.
  - `message` `string` _(required)_: A human-readable explanation of what went wrong.
- `requestId` `string` _(required)_: The id of this request — include it when contacting support.

#### `429`: Rate limit exceeded. On endpoints that accept MPP, over-quota unpaid requests return `402 Payment Required` instead.

Headers:

- `RateLimit-Limit` `integer`: How many requests you may make in the current time window. Not sent on cached responses or `402` payment challenges.
- `RateLimit-Remaining` `integer`: How many requests you have left in the current window before you are rate-limited. Not sent on cached responses or `402` payment challenges.
- `RateLimit-Reset` `integer`: When the current window resets, as a Unix timestamp in seconds. Not sent on cached responses or `402` payment challenges.
- `RateLimit-Scope` `string`: Which quota this request counted against (e.g. `data:read`). Not sent on cached responses or `402` payment challenges.
- `tempo-request-id` `string`: A unique id for this request, returned on every response (and as `requestId` in error bodies). Include it when contacting support so we can find your request.
- `Retry-After` `integer`: How many seconds to wait before trying again. Sent with `429` (rate-limited) responses.

Body (`application/json`):

- `error` `object` _(required)_: What went wrong.
  - `code` `string` _(required)_: A short, stable code you can branch on in your code (e.g. `token_not_found`).
  - `details` `object[]`: A list of specific problems, when the error is about your request (e.g. invalid fields).
    - `message` `string` _(required)_: A specific thing that went wrong, in plain language (e.g. why a field failed validation).
    - `path` `string | number[]`: Where the problem is, as a path into your request (e.g. `["query", "limit"]`). Present for validation errors.
  - `message` `string` _(required)_: A human-readable explanation of what went wrong.
- `requestId` `string` _(required)_: The id of this request — include it when contacting support.

#### `500`: Internal server error.

Body (`application/json`):

- `error` `object` _(required)_: What went wrong.
  - `code` `string` _(required)_: A short, stable code you can branch on in your code (e.g. `token_not_found`).
  - `details` `object[]`: A list of specific problems, when the error is about your request (e.g. invalid fields).
    - `message` `string` _(required)_: A specific thing that went wrong, in plain language (e.g. why a field failed validation).
    - `path` `string | number[]`: Where the problem is, as a path into your request (e.g. `["query", "limit"]`). Present for validation errors.
  - `message` `string` _(required)_: A human-readable explanation of what went wrong.
- `requestId` `string` _(required)_: The id of this request — include it when contacting support.

#### `502`: Could not read Earn vault data.

Body (`application/json`):

- `error` `object` _(required)_: What went wrong.
  - `code` `string` _(required)_: A short, stable code you can branch on in your code (e.g. `token_not_found`).
  - `details` `object[]`: A list of specific problems, when the error is about your request (e.g. invalid fields).
    - `message` `string` _(required)_: A specific thing that went wrong, in plain language (e.g. why a field failed validation).
    - `path` `string | number[]`: Where the problem is, as a path into your request (e.g. `["query", "limit"]`). Present for validation errors.
  - `message` `string` _(required)_: A human-readable explanation of what went wrong.
- `requestId` `string` _(required)_: The id of this request — include it when contacting support.

### Example request

```bash
curl 'https://api.tempo.xyz/v1/earn/vaults/0xbe058e1c4df8a4366a387bf595b284246a93039e?chainId=4217&include=access,apy,capabilities,token.logoUri,tvl,zone&apy.window=7d'
```

```ts
fetch('https://api.tempo.xyz/v1/earn/vaults/0xbe058e1c4df8a4366a387bf595b284246a93039e?chainId=4217&include=access,apy,capabilities,token.logoUri,tvl,zone&apy.window=7d')
```