Vault Agent API integration

The Vault Agent is the current YieldSeeker agent type. Its API manages a base asset across approved DeFi vault opportunities and exposes yield, position, activity, and preference operations.

Lifecycle

1. Create the agent with type: vault.
2. Get its Agent Wallet address.
3. Fund the wallet with a supported base asset.
4. For a standard user request, deploy after the Agent Wallet holds at least $10 worth of its base asset. A validated integrator request may deploy before funding.
5. Read positions, activity, and performance as the agent operates.
6. Withdraw positions and wallet balances before deactivation.

See Creating an agent via API for the generic create operation.

Deposits and withdrawals

Deposits and wallet withdrawals use unsigned transactions that the user signs. prepareDeposit transfers from the connected wallet to the Agent Wallet; prepareWithdrawal moves the idle base asset back to the user’s wallet. withdrawFromPosition uses the Agent Wallet’s permitted execution path to move a vault position back into the Agent Wallet. None of these routes give integrators owner-key access or accept an arbitrary recipient.

Deposit

1. Call prepareDeposit to get unsigned transaction data for transferring the base asset from the user’s connected wallet to the Agent Wallet.
2. Have the user sign and submit that transaction with their own wallet.
3. After the transaction confirms, call:

GET /v1/users/{userId}/agents/{agentId}/snapshot?shouldForceRefresh=true

This refreshes the agent snapshot so the API reflects the confirmed deposit.

Withdraw from a vault position

Call withdrawFromPosition to move assets from an approved vault position back into the Agent Wallet. This operation is executed through the agent’s permitted session-key path. It does not send assets to the user or to an arbitrary address.

Withdraw from the Agent Wallet

1. Call prepareWithdrawal to get unsigned transaction data for withdrawing the idle base-asset balance to the user’s connected wallet.
2. Have the user sign and submit the transaction with their own wallet.
3. After the transaction confirms, call:

GET /v1/users/{userId}/agents/{agentId}/snapshot?shouldForceRefresh=true

This refreshes the agent snapshot so the API reflects the confirmed withdrawal.

See the API authentication guide for signed API requests and the generated API reference for exact request and response schemas.

List vaults

GET /v1/chains/{chainId}/assets/{assetAddress}/vault-options

This public operation lists available vault opportunities without forcing a refresh. GET /v1/chains/{chainId}/assets/{assetAddress}/yield-options is a deprecated alias that returns the same vaults under yieldOptions. The backend also defines POST /v1/vault-options/refresh, which refreshes every supported chain and asset, but it is cron-authenticated rather than a client refresh operation. Availability, APY, liquidity, and rewards can change.

Expected APY

GET /v1/chains/{chainId}/assets/{assetAddress}/apy-stats?rulePreset=explorative

This public operation returns active agents’ 7-day and 30-day APY for a supported base asset, weighted by how much each agent holds: apyMoneyWeighted7d/apyMoneyWeighted30d are the averages, and the 25th/50th/75th percentiles split the money, not the agents. Omit rulePreset to include every preset. These are realized returns, so they are already after the platform fee. For each window, only agents worth at least $100 with at least that many days of history count, users in a YieldSeeker reward campaign (Merkl or boost) that ran during the window are left out because campaign rewards inflate their APY, and the fields are null when fewer than 20 agents qualify.

Show expectedApy7d or expectedApy30d, which are never null. When enough agents qualify each is the matching money-weighted average. Otherwise it is an estimate: the APY the allocation engine would earn today for a $10,000 deposit on that preset, from each chosen vault’s 7-day or 30-day average APY, after the platform fee. Present it as a guide based on recent results, not a promise.

Preferences and simulations

All preference and simulation endpoints are user-scoped. Authenticate them with the user’s signed wallet token. They change agent configuration or return projections; they do not give an integrator owner permission over the Agent Wallet.

Read preferences and rules

GET /v1/users/{userId}/agents/{agentId}/memories
GET /v1/users/{userId}/agents/{agentId}/memories/effective-rules
GET /v1/users/{userId}/agents/{agentId}/memories/active-limit

Use memories for saved natural-language preferences, effective-rules to inspect the rules applied to allocation decisions, and active-limit for the agent’s active-memory capacity.

effective-rules returns memory-derived userRules and computed defaultRules separately. A user rule replaces a default of the same type.

Save a preference

POST /v1/users/{userId}/agents/{agentId}/memories
POST /v1/users/{userId}/agents/{agentId}/memories/{memoryId}
POST /v1/users/{userId}/agents/{agentId}/memories/{memoryId}/delete

Create a memory with the preference you want the agent to retain. Update its content or active state when it changes. Delete it when it should no longer be part of the agent’s configuration. A memory is interpreted as an allocation preference, not as arbitrary transaction calldata.

When replacing a filter or list-based preference, read the current effective rules first and write the complete desired end state. A new memory can replace or constrain an existing rule rather than merging with it.

For a broad profile change, update the agent with:

PATCH /v1/users/{userId}/agents/{agentId}

The supported presets are conservative and explorative (the default). Use memories for detailed preferences that should be compiled into allocation rules.

Simulate before saving

POST /v1/users/{userId}/agents/{agentId}/simulate
GET /v1/users/{userId}/simulate/credits

runAgentSimulation previews how one or more memory strings would change derived rules, vault scores, and target allocations. It does not save the memories or execute an allocation. Each simulation consumes one credit. Use getSimulationCreditsStatus to show the remaining daily credits; credits reset daily in UTC and Pro users receive a higher limit.

Positions and activity

GET /v1/users/{userId}/agents/{agentId}/vault-positions
GET /v1/users/{userId}/agents/{agentId}/actions

These operations return current positions and previous allocation decisions. Treat position data as a snapshot that can become stale while blockchain/provider data is updated. GET /v1/users/{userId}/agents/{agentId}/yield-positions is a deprecated alias that returns the same positions under yieldPositions, each with yieldOption in place of vaultOption.

Each vault position has netApy: the vault’s current riskAdjustedApy after the agent’s platform fee. In a rebalance action’s details, each entry in deposits and withdrawals has apy and netApy, the vault’s APY when the move ran, before and after the fee. Older actions don’t have them. Both after-fee values are estimates, because the fee is only charged on realized positive yield.

Deactivation

Deactivation fails while the Agent Wallet still holds value. Withdraw vault positions and the remaining wallet balance before deactivating.

Do not retry deactivation blindly; inspect the returned error and current wallet state first.

Authoritative reference

The generated API reference owns exact request/response schemas. The Vault Agent pages explain the same behavior without requiring API knowledge.