# Build on Obento

> Read the vault's live state, deposit through the gateway, and feed these docs to an agent.

## Read the vault

`GET https://obentoapp.com/api/vault` returns the vault's live state as JSON. An abridged example:

```json
{
  "price": "1000000",
  "priceFresh": true,
  "paused": false,
  "tvl": 0,
  "ready": 0,
  "apy": 0.0436,
  "grossApy": 0.0484,
  "performanceFeeBps": 1000,
  "places": [
    { "key": "0xf42f5795D9ac7e9D757dB633D693cD548Cfd9169", "value": 0, "share": 0, "apy": 0.0539 }
  ]
}
```

| Field | Meaning |
|---|---|
| `price` | USDC per obUSD, with 6 decimals |
| `priceFresh` | Whether the price is less than an hour old |
| `tvl` | Savings in the vault, in USDC |
| `ready` | Ready cash for instant withdrawals, in USDC |
| `apy` | The vault's rate after the fee. While the vault is empty, the rate its first deposit would earn |
| `places` | Each place's value in USDC, its share of the vault and its rate before the fee |

## Read a saver's earnings and activity

`GET https://obentoapp.com/api/earnings?address=0x…` returns what an address has put in, taken out and holds now, in USDC with 6 decimals; what it has earned and what Autopilot's fee came to, in dollars; and its activity, newest first. It reads the vault's own events for that address, so obUSD sent between wallets and bonuses are not counted as earnings.

```json
{
  "deposited": "1000000000", "withdrawn": "0", "value": "1002500000", "earned": 2.5, "fee": 0.28,
  "activity": [{ "kind": "added", "at": 1791200000, "tx": "0x…", "amount": 1000 }]
}
```

Each entry is `added`, `withdrew` (with `to`, and a `status` of `paid`, `queued` or `returned`) or `bonus` (with `saved`). `at` is a Unix time in seconds.

## Read Autopilot's journal

`GET https://obentoapp.com/api/journal` returns the last 30 days, newest first: each `move` between places, each queued withdrawal Autopilot `paid`, and each time the vault was `paused` or `resumed`, with its transaction. The [journal page](/docs/journal) reads the same data.

## Deposit and withdraw

The vault is an ERC-4626 vault for USDC with 6-decimal shares (obUSD). Deposits and withdrawals go through the gateway:

- `deposit(vault, assets, minSharesOut, receiver, partnerId)`
- `redeem(vault, shares, minAssetsOut, receiver, partnerId)`

Approve the gateway first: USDC for a deposit, obUSD for a withdrawal. A withdrawal larger than the ready cash joins the queue and is paid on Autopilot's next pass. Addresses are on the [contracts page](/docs/contracts).

## For agents

- [/llms.txt](/llms.txt) lists every page.
- [/docs/llms-full.txt](/docs/llms-full.txt) holds all the docs in one file.
- Every page is also Markdown: add `.md` to its address, for example [/docs/fees.md](/docs/fees.md).