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

# Earn vault endpoints

> Search yield vaults, fetch one vault, list a wallet's vault positions, and get the transactions that withdraw a position.

These endpoints back **Earn** over REST. With them and [`POST /route`](https://docs.trustware.io/api-reference/route#vault-deposits), you can find a vault, deposit into it from any supported asset, and withdraw later, without the SDK. The SDK equivalents are in [Earn with the headless core](https://docs.trustware.io/guides/earn-headless.md).

Every endpoint takes the same `X-API-Key` header and rate limits as `POST /route`. See [authentication](https://docs.trustware.io/api-reference/overview.md#authentication). A missing or invalid key returns `401`.

## The flow

**1. Find a vault**

Call [`GET /vaults`](#search-vaults) to search, or [`GET /vaults/{network}/{vaultId}`](#get-a-vault) for a vault you already know.

**2. Deposit**

Call [`POST /route`](https://docs.trustware.io/api-reference/route#vault-deposits) with `vault: { vaultId, network }`. Set `toChain` to the vault's `network.chainId`, `toToken` to its `asset.address`, and `toAddress` to the EVM address that receives the position. Then sign, submit the receipt, and poll status as for any route.

**3. Show positions**

Call [`GET /vaults/positions/{address}`](#list-positions).

**4. Withdraw**

Call [`GET /vaults/redeem/{network}/{vaultId}`](#get-withdrawal-transactions), then sign and send each returned transaction in order from the wallet that holds the position.

Successful responses wrap the result in `data`. Errors return `error` with a message, as on every endpoint. When vault data can't be fetched, the endpoints return `503`. Search and detail results are cached, so APY and TVL can lag the source by an hour or more. Positions are cached for up to a minute.

## Search vaults

`GET https://api.trustware.io/api/v1/routes/vaults`

Returns one page of vaults matching your filters. Repeat a list parameter to pass several values, such as `?allowedNetworks=base&allowedNetworks=arbitrum`.

| Parameter | Description |
| - | - |
| `allowedAssets` | Asset symbols to include, such as `USDC`. |
| `allowedNetworks` | Network names to include, such as `base`. |
| `allowedProtocols` | Protocols to include, by protocol ID or name. |
| `disallowedProtocols` | Protocols to exclude, by protocol ID or name. Ignored when `allowedProtocols` is set. |
| `minTvl` | Minimum TVL in USD. |
| `minApy` | Minimum APY as a decimal fraction, such as `0.05` for 5%. |
| `sortBy` | One of `tvl`, `apy1day`, `apy7day`, `apy30day`, or `apy90day`. |
| `sortOrder` | `asc` or `desc`. Defaults to `asc`. |
| `page` | Zero-based page to fetch. Pass the previous response's `nextPage`. |
| `perPage` | Vaults per page, from 1 to 10. Defaults to 10. |

Every parameter is optional. A `perPage` outside 1 to 10, a `page` or `perPage` that isn't an integer, or a `minTvl` or `minApy` that isn't a number returns `400`.

```json theme={null}
{
  "data": {
    "vaults": [
      {
        "vaultId": "0xYourVaultAddress",
        "address": "0xYourVaultAddress",
        "name": "USDC Vault",
        "network": { "name": "base", "chainId": 8453 },
        "asset": {
          "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
          "name": "USD Coin",
          "symbol": "USDC",
          "decimals": 6
        },
        "protocol": { "protocolId": "example", "name": "example", "displayName": "Example" },
        "curator": { "name": "example", "displayName": "Example", "websiteUrl": "https://example.com" },
        "tags": [],
        "apy": {
          "1hour": { "base": 0, "reward": 0, "total": 0 },
          "1day": { "base": 0, "reward": 0, "total": 0 },
          "7day": { "base": 0, "reward": 0, "total": 0 },
          "30day": { "base": 0, "reward": 0, "total": 0 }
        },
        "tvl": { "usd": "0", "native": "0" },
        "score": {
          "vaultScore": 0,
          "vaultTvlScore": 0,
          "protocolTvlScore": 0,
          "holderScore": 0,
          "assetScore": 0,
          "totalScorePenalty": 0
        },
        "isTransactional": true,
        "warnings": [],
        "flags": []
      }
    ],
    "nextPage": 1
  }
}
```

`nextPage` is absent on the last page. Each vault has the shape of [`VaultSummary`](https://docs.trustware.io/api-reference/types#vaultsummary). To deposit, pass `vaultId` and `network.name` as the route's `vault`, `network.chainId` as `toChain`, and `asset.address` as `toToken`. A flag carries `content`, `severity`, and an optional `endDate` as a Unix timestamp.

## Get a vault

`GET https://api.trustware.io/api/v1/routes/vaults/{network}/{vaultId}`

Returns one vault as `data`, with the same shape as a search result.

| Path parameter | Description |
| - | - |
| `network` | The vault's network name, such as `base`. |
| `vaultId` | The vault's contract address. |

## List positions

`GET https://api.trustware.io/api/v1/routes/vaults/positions/{address}`

Returns every vault position the wallet holds, including vaults you don't offer.

```json theme={null}
{
  "data": [
    {
      "vaultId": "0xYourVaultAddress",
      "address": "0xYourVaultAddress",
      "name": "USDC Vault",
      "network": { "name": "base", "chainId": 8453 },
      "asset": {
        "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
        "name": "USD Coin",
        "symbol": "USDC",
        "decimals": 6,
        "balanceNative": "0",
        "balanceUsd": "0",
        "unclaimedNative": "0",
        "unclaimedUsd": "0",
        "positionValueInAsset": "0"
      },
      "protocol": { "protocolId": "example", "name": "example", "displayName": "Example" },
      "lpToken": {
        "address": "0xYourVaultAddress",
        "name": "USDC Vault Share",
        "symbol": "vUSDC",
        "decimals": 18,
        "balanceNative": "0",
        "balanceUsd": "0"
      },
      "isTransactional": true,
      "apy": { "base": 0, "reward": 0, "total": 0 }
    }
  ]
}
```

| Field | Description |
| - | - |
| `lpToken.balanceUsd` | This position's value in USD. Use it to display the position. |
| `asset.balanceUsd` | The wallet's total balance of the asset token, repeated on every position row. It is not this position's value. |
| `asset.positionValueInAsset` | This position's value in the asset's base units, scaled by `asset.decimals`. |
| `lpToken.decimals` | Decimals of the vault's share token. A partial withdrawal `amount` uses these. |
| `apy` | A single window, unlike a vault's `apy`. |

Treat a `null` `data` as no positions.

## Get withdrawal transactions

`GET https://api.trustware.io/api/v1/routes/vaults/redeem/{network}/{vaultId}`

Returns the unsigned transactions that withdraw a position. A withdrawal is not a route. It runs on the vault's own chain, the vault's asset returns to `address`, and there is no intent, receipt, or status to track.

| Parameter | In | Required | Description |
| - | - | - | - |
| `network` | Path | Yes | The position's `network.name`. |
| `vaultId` | Path | Yes | The position's `vaultId`. |
| `address` | Query | Yes | The wallet that owns the position. The asset is returned to it, so it must also sign the transactions. |
| `assetAddress` | Query | Yes | The position's `asset.address`. Required even with `all=true`. |
| `all` | Query | Unless `amount` is set | `true` withdraws the whole position. |
| `amount` | Query | Unless `all=true` | Vault shares to withdraw, in base units of the share token (`lpToken.decimals`). Not scaled by `asset.decimals`. |

A request without `address` or `assetAddress`, with neither `all=true` nor `amount`, or with an `all` that isn't a boolean returns `400`.

```json theme={null}
{
  "data": [
    {
      "name": "Redeem all USDC from USDC Vault",
      "tx": {
        "to": "0xYourVaultAddress",
        "chainId": 8453,
        "data": "0xYourEncodedCallData",
        "value": ""
      }
    }
  ]
}
```

| Field | Description |
| - | - |
| `name` | A label for the step. |
| `tx.to` | The contract to call. |
| `tx.chainId` | The chain to send on, the vault's own chain. |
| `tx.data` | Calldata to send. |
| `tx.value` | Native value to send, in wei. An empty string means `0`. |

Sign and send each transaction in the order returned, from `address`, on `tx.chainId`. Wait for each one to confirm before you send the next, and stop if one fails.

To move the withdrawn asset somewhere else, build a new route with it as the source once the withdrawal confirms.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.