Docs/sdk 0.15.0 updates

api-reference/endpoints/get-earn-pools.mdx

@@ -1,8 +1,12 @@
 ---
-title: GetEarnPools
+title: GetEarnPools (deprecated)
 openapi: ../trails-api.gen.json post /rpc/Trails/GetEarnPools
 ---
 
+<Warning>
+`GetEarnPools` is deprecated. Use [YieldGetMarkets](/api-reference/endpoints/yield-get-markets) instead — it provides richer market data, filtering, and pagination.
+</Warning>
+
 ## Overview
 
 The `GetEarnPools` endpoint returns aggregated yield-bearing pool information from supported DeFi protocols such as Aave and Morpho. Use this to display earning opportunities to users and build Earn mode integrations.

api-reference/endpoints/yield-create-enter-action.mdx

@@ -0,0 +1,98 @@
+---
+title: YieldCreateEnterAction
+description: "Generate unsigned deposit transaction calldata for a DeFi yield market"
+openapi: ../trails-api.gen.json post /rpc/Trails/YieldCreateEnterAction
+---
+
+## Overview
+
+`YieldCreateEnterAction` returns the unsigned transaction payload needed to deposit into a DeFi yield market. This is the low-level endpoint that backs the `lend` and `deposit` composable actions in the SDK.
+
+Use this endpoint when building custom DeFi UIs outside React, or when you need to construct the calldata manually before passing it to Trails via the `to.calldata` param on `QuoteIntent`.
+
+For React apps, use the `lend()` or `deposit()` action builders with `useTrailsSendTransaction` — they call this endpoint internally.
+
+## Request Parameters
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `earnMarketId` | string | Yes | Market ID from `YieldGetMarkets` |
+| `userWalletAddress` | string | Yes | Address of the depositing wallet |
+| `args` | object | No | Market-specific arguments (varies by protocol) |
+
+## Response
+
+Returns `payload` containing unsigned transaction data:
+
+| Field | Description |
+|-------|-------------|
+| `transactions` | Array of transaction objects to execute |
+| `transactions[].to` | Contract address |
+| `transactions[].data` | ABI-encoded calldata |
+| `transactions[].value` | ETH value (for native token deposits) |
+
+## Examples
+
+### Build a deposit calldata for Aave
+
+```typescript
+const response = await fetch('https://trails-api.sequence.app/rpc/Trails/YieldCreateEnterAction', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'X-Access-Key': 'YOUR_ACCESS_KEY',
+  },
+  body: JSON.stringify({
+    earnMarketId: 'base-usdc-aave-v3-lending',
+    userWalletAddress: '0xYourWalletAddress',
+  }),
+})
+
+const { payload } = await response.json()
+const action = JSON.parse(payload)
+
+// Pass action.transactions[0].data to QuoteIntent as to.calldata
+```
+
+### With protocol-specific arguments
+
+Some markets accept additional arguments (e.g. slippage, referral codes):
+
+```typescript
+const response = await fetch('https://trails-api.sequence.app/rpc/Trails/YieldCreateEnterAction', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'X-Access-Key': 'YOUR_ACCESS_KEY',
+  },
+  body: JSON.stringify({
+    earnMarketId: 'ethereum-usdc-morpho-0x...',
+    userWalletAddress: '0xYourWalletAddress',
+    args: {
+      referralCode: 0,
+    },
+  }),
+})
+```
+
+## SDK alternative
+
+For React, use the `lend` or `deposit` builders with `useTrailsSendTransaction`:
+
+```tsx
+import { useTrailsSendTransaction, lend, deposit } from '0xtrails'
+
+const { sendTransaction } = useTrailsSendTransaction({
+  actions: [
+    lend({ marketId: 'base-usdc-aave-v3-lending', amount: '100' }),
+  ],
+})
+```
+
+See [Composable Actions](/use-cases/composable-actions) for the full SDK approach.
+
+## See also
+
+- [YieldCreateExitAction](/api-reference/endpoints/yield-create-exit-action) — Withdraw from a position
+- [YieldGetMarkets](/api-reference/endpoints/yield-get-markets) — Discover market IDs
+- [Composable Actions](/use-cases/composable-actions) — SDK builders for DeFi deposits

api-reference/endpoints/yield-create-exit-action.mdx

@@ -0,0 +1,106 @@
+---
+title: YieldCreateExitAction
+description: "Generate unsigned withdrawal transaction calldata for a DeFi yield position"
+openapi: ../trails-api.gen.json post /rpc/Trails/YieldCreateExitAction
+---
+
+## Overview
+
+`YieldCreateExitAction` returns the unsigned transaction payload needed to withdraw from a DeFi yield position. It is the counterpart to `YieldCreateEnterAction`.
+
+Use this endpoint to build withdrawal UIs or construct exit calldata for Trails routes. For React apps, the composable action builders handle this automatically.
+
+## Request Parameters
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `earnMarketId` | string | Yes | Market ID from `YieldGetMarkets` |
+| `userWalletAddress` | string | Yes | Address of the withdrawing wallet |
+| `args` | object | No | Market-specific arguments (e.g. amount, shares) |
+
+## Response
+
+Returns `payload` containing unsigned transaction data:
+
+| Field | Description |
+|-------|-------------|
+| `transactions` | Array of transaction objects to execute |
+| `transactions[].to` | Contract address |
+| `transactions[].data` | ABI-encoded calldata |
+| `transactions[].value` | ETH value (for native token withdrawals) |
+
+## Examples
+
+### Withdraw from an Aave lending position
+
+```typescript
+const response = await fetch('https://trails-api.sequence.app/rpc/Trails/YieldCreateExitAction', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'X-Access-Key': 'YOUR_ACCESS_KEY',
+  },
+  body: JSON.stringify({
+    earnMarketId: 'base-usdc-aave-v3-lending',
+    userWalletAddress: '0xYourWalletAddress',
+  }),
+})
+
+const { payload } = await response.json()
+const action = JSON.parse(payload)
+```
+
+### Withdraw a specific amount
+
+Use `args` to pass withdrawal parameters for markets that require them (e.g. partial withdrawals):
+
+```typescript
+const response = await fetch('https://trails-api.sequence.app/rpc/Trails/YieldCreateExitAction', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'X-Access-Key': 'YOUR_ACCESS_KEY',
+  },
+  body: JSON.stringify({
+    earnMarketId: 'ethereum-usdc-morpho-0x...',
+    userWalletAddress: '0xYourWalletAddress',
+    args: {
+      amount: '1000000', // 1 USDC in wei
+    },
+  }),
+})
+```
+
+## Common pattern: check balance then exit
+
+```typescript
+// 1. Check what positions the wallet holds
+const balancesRes = await fetch('https://trails-api.sequence.app/rpc/Trails/YieldGetAggregateBalances', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json', 'X-Access-Key': 'YOUR_ACCESS_KEY' },
+  body: JSON.stringify({ queries: [{ address: '0xYourWallet', network: 'base' }] }),
+})
+const { payload: balPayload } = await balancesRes.json()
+const balances = JSON.parse(balPayload)
+
+// 2. Build exit calldata for each position
+for (const position of balances) {
+  const exitRes = await fetch('https://trails-api.sequence.app/rpc/Trails/YieldCreateExitAction', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', 'X-Access-Key': 'YOUR_ACCESS_KEY' },
+    body: JSON.stringify({
+      earnMarketId: position.yieldId,
+      userWalletAddress: '0xYourWallet',
+    }),
+  })
+  const { payload: exitPayload } = await exitRes.json()
+  const exitAction = JSON.parse(exitPayload)
+  // Use exitAction.transactions to build and submit the withdrawal
+}
+```
+
+## See also
+
+- [YieldCreateEnterAction](/api-reference/endpoints/yield-create-enter-action) — Deposit into a position
+- [YieldGetAggregateBalances](/api-reference/endpoints/yield-get-balances) — Check existing positions before exiting
+- [YieldGetMarkets](/api-reference/endpoints/yield-get-markets) — Discover market IDs

api-reference/endpoints/yield-get-balances.mdx

@@ -0,0 +1,117 @@
+---
+title: YieldGetAggregateBalances
+description: "Fetch a wallet's earn balances across chains and yield positions"
+openapi: ../trails-api.gen.json post /rpc/Trails/YieldGetAggregateBalances
+---
+
+## Overview
+
+`YieldGetAggregateBalances` returns a wallet's active yield positions across one or more chains. Use this to show users their current DeFi holdings — principal, earned yield, and which markets they are in.
+
+The SDK's `useEarnBalances` hook wraps this endpoint — prefer it in React apps.
+
+## Request Parameters
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `queries` | object[] | Yes | Array of 1–25 balance queries |
+
+Each query object:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `address` | string | Yes | Wallet address to look up |
+| `network` | string | Yes | Network identifier (e.g. `"ethereum"`, `"base"`, `"polygon"`) |
+
+<Note>
+You can pass up to 25 queries per request, enabling multi-chain balance lookups in a single call.
+</Note>
+
+## Response
+
+Returns `payload` containing balance records. Each balance entry includes:
+
+| Field | Description |
+|-------|-------------|
+| `yieldId` | Market ID — matches the `id` field from `YieldGetMarkets` |
+| `address` | Wallet address |
+| `network` | Network the position is on |
+| `amount` | Balance amount in the market's token |
+| `amountUsd` | USD value of the position |
+
+## Examples
+
+### Fetch balances on a single chain
+
+```typescript
+const response = await fetch('https://trails-api.sequence.app/rpc/Trails/YieldGetAggregateBalances', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'X-Access-Key': 'YOUR_ACCESS_KEY',
+  },
+  body: JSON.stringify({
+    queries: [
+      {
+        address: '0xYourWalletAddress',
+        network: 'base',
+      },
+    ],
+  }),
+})
+
+const { payload } = await response.json()
+const balances = JSON.parse(payload)
+
+balances.forEach(position => {
+  console.log(`${position.yieldId}: ${position.amountUsd} USD`)
+})
+```
+
+### Multi-chain balance lookup
+
+```typescript
+const response = await fetch('https://trails-api.sequence.app/rpc/Trails/YieldGetAggregateBalances', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'X-Access-Key': 'YOUR_ACCESS_KEY',
+  },
+  body: JSON.stringify({
+    queries: [
+      { address: '0xYourWalletAddress', network: 'base' },
+      { address: '0xYourWalletAddress', network: 'ethereum' },
+      { address: '0xYourWalletAddress', network: 'polygon' },
+    ],
+  }),
+})
+
+const { payload } = await response.json()
+const balances = JSON.parse(payload)
+```
+
+## SDK alternative
+
+In React, use the `useEarnBalances` hook:
+
+```tsx
+import { useEarnBalances } from '0xtrails'
+
+// Single chain
+const { data: balances } = useEarnBalances({
+  walletAddress: '0xYourWalletAddress',
+  chain: 'base',
+})
+
+// Multiple chains
+const { data: balances } = useEarnBalances({
+  walletAddress: '0xYourWalletAddress',
+  chains: ['base', 'ethereum', 'polygon'],
+})
+```
+
+## See also
+
+- [YieldGetMarkets](/api-reference/endpoints/yield-get-markets) — Match `yieldId` against market IDs
+- [YieldCreateExitAction](/api-reference/endpoints/yield-create-exit-action) — Build withdrawal transactions for active positions
+- [Markets & Providers](/sdk/composable-actions/markets-and-providers) — SDK hooks reference