Skip to content

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

Section titled “Lifecycle”
  1. Create the agent with type: vault.
  2. Get its Agent Wallet address.
  3. Fund the wallet with a supported base asset.
  4. Deploy the agent after its wallet holds at least $10 worth of the base asset.
  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

Section titled “Deposits and withdrawals”

The user controls every transfer into or out of the Agent Wallet. The YieldSeeker server has no owner permission to spend from the user’s connected wallet or withdraw assets from the Agent Wallet. This separation is deliberate: integrators can manage an agent through the API without receiving wallet signing authority.

Deposit

Section titled “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

Section titled “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

Section titled “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

Section titled “List vaults”
GET /v1/chains/{chainId}/assets/{assetAddress}/yield-options

This public operation lists the currently available vault opportunities for a chain and base asset without forcing a refresh. It has no refresh operation. Use the returned vault addresses and metadata when building agent memories; availability, APY, liquidity, and rewards can change.

Preferences and simulations

Section titled “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

Section titled “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 the saved natural-language preferences, effective-rules for the rules currently applied to allocation decisions, and active-limit for the agent’s active-memory capacity.

Save a preference

Section titled “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}

Send the desired rulePreset in the request body. Use memories for detailed preferences that should be compiled into allocation rules.

Simulate before saving

Section titled “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

Section titled “Positions and activity”
GET /v1/users/{userId}/agents/{agentId}/yield-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.

Deactivation

Section titled “Deactivation”

Deactivation fails while the agent still holds assets or positions. Withdraw vault positions into the Agent Wallet, then have the user withdraw the wallet’s idle base-asset balance before deactivating.

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

Authoritative reference

Section titled “Authoritative reference”

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