v1.0.0
OpenAPI 3.0.3

YieldSeeker API

The documented external subset of the YieldSeeker v1 API.

Authentication

Authorization is required for user-scoped endpoints. Send the complete header value Signature <signature-token>, where the token is the base64-encoded authentication token produced by the wallet authentication flow.

User signatures are Sign-In with Ethereum (SIWE, EIP-4361) messages. Generate a SIWE message for the caller's wallet (domain must be one of YieldSeeker's allowed auth domains, and issued_at must be no more than 30 days old), have the wallet sign it, then base64-encode a JSON object of the form {"message": "<siwe-message>", "signature": "<hex-signature>"} to produce the signature token. A message with an expirationTime in the past, or one issued more than 30 days ago, is rejected. For complete signing and header instructions, see the developer authentication guide. For Vault Agent lifecycle, vault discovery, and user-controlled funding and withdrawal behavior, see the Vault Agent API integration guide.

X-Api-Key is optional. When provided, it identifies the integrator and is validated against the request origin. Omit it for normal first-party v1 requests.

Rate limits

Most operations are rate limited per caller (by user for signed requests, by IP for public ones), across one or more rolling windows. Each operation's description states its current limit; a request over that limit receives a 429 response with a Retry-After header giving the number of seconds to wait before retrying. Limits can change; treat the 429 response and Retry-After header as authoritative, not the documented number alone. See the rate limits guide for the current tiers.

Client Libraries
Shell Curl

System

​

Platform-wide endpoints that need no user context: service health, on-chain contract status, and the assets/chains YieldSeeker currently supports. Use these to check the API is up and to discover what you can build against before creating any users or agents.

System Operations
getHealth

Check API health

​

Lightweight liveness check. Returns ok if the API process is reachable; does not verify database, blockchain, or downstream provider connectivity.

Rate limited to 30 requests/minute, 300 requests/hour.

Responses

  • 200
    Type: HealthResponse

    Successful response

    • health
      Type: Health
      required
      Properties: 1
    application/json
Request Example for get/v1/health
curl /v1/health

{
  "health": {
    "status": "ok"
  }
}

Successful response

getOnchainStatus

Get on-chain status

​

Returns the on-chain status of platform contracts: timelock configuration, pending operations, and role assignments.

Rate limited to 30 requests/minute, 300 requests/hour.

Responses

  • 200
    Type: GetOnchainStatusResponse

    Successful response

    • onchainStatus
      Type: OnchainStatus
      required
      Properties: 5
    application/json
Request Example for get/v1/onchain-status
curl /v1/onchain-status

{
  "onchainStatus": {
    "chainId": 1,
    "timelockDelaySeconds": 1,
    "contracts": [
      {
        "key": "string",
        "name": "string",
        "address": "string",
        "category": "string",
        "fieldValues": [
          {
            "name": "string",
            "value": "string",
            "valueType": "string",
            "valueLabel": "string"
          }
        ],
        "roles": [
          {
            "roleKey": "string",
            "roleLabel": "string",
            "members": [
              {
                "address": "string",
                "label": "string"
              }
            ]
          }
        ]
      }
    ],
    "registryEntries": [
      {
        "target": "string",
        "targetName": "string",
        "adapter": "string",
        "adapterName": "string"
      }
    ],
    "timelockOperations": [
      {
        "operationId": "string",
        "status": "string",
        "target": "string",
        "targetName": "string",
        "functionName": "string",
        "parameters": [
          {
            "name": "string",
            "value": "string",
            "valueType": "string",
            "valueLabel": "string"
          }
        ],
        "scheduledTransactionHash": "string",
        "executedTransactionHash": "string",
        "delay": 1,
        "unlocksAt": "string"
      }
    ]
  }
}

Successful response

listSupportedAssets

List supported assets

​

Lists the base assets (e.g. USDC, WETH) supported for agents on a given chain, along with their observed APY range.

Rate limited to 30 requests/minute, 300 requests/hour.

Path Parameters

  • chainId
    Type: integer
    required

    Integer numbers.

Responses

  • 200
    Type: GetSupportedAssetsResponse

    Successful response

    • supportedAssets
      Type: array of SupportedAsset
      required
      Properties: 3
    application/json
Request Example for get/v1/chains/{chainId}/supported-assets
curl /v1/chains/8453/supported-assets

{
  "supportedAssets": [
    {
      "asset": {
        "chainId": 1,
        "address": "string",
        "decimals": 1,
        "name": "string",
        "symbol": "string",
        "logoUri": "string",
        "totalSupply": "string",
        "isSpam": true
      },
      "minApy": 1,
      "maxApy": 1
    }
  ]
}

Successful response

listBorrowPairs

List borrow pairs

​

Lists borrow pairs with a usable lending market, ordered by collateral and borrow asset symbol.

Rate limited to 30 requests/minute, 300 requests/hour.

Path Parameters

  • chainId
    Type: integer
    required

    Integer numbers.

Responses

  • 200
    Type: GetBorrowPairsResponse

    Successful response

    • borrowPairs
      Type: array of BorrowPair
      required
      Properties: 4
    application/json
Request Example for get/v1/chains/{chainId}/borrow-pairs
curl /v1/chains/8453/borrow-pairs

{
  "borrowPairs": [
    {
      "collateralAsset": {
        "chainId": 1,
        "address": "string",
        "decimals": 1,
        "name": "string",
        "symbol": "string",
        "logoUri": "string",
        "totalSupply": "string",
        "isSpam": true
      },
      "borrowAsset": {
        "chainId": 1,
        "address": "string",
        "decimals": 1,
        "name": "string",
        "symbol": "string",
        "logoUri": "string",
        "totalSupply": "string",
        "isSpam": true
      },
      "netBorrowApy": 1,
      "maxNetBorrowApy": 1
    }
  ]
}

Successful response

getAssetApyStats

Get APY statistics for an asset

​

Returns active agents' realized 7-day APY for a supported base asset, weighted by agent value (average and 25th/50th/75th percentiles), optionally limited to one rule preset, plus expectedApy7d to show a new agent. Realized APY is already after platform fees.

Rate limited to 30 requests/minute, 300 requests/hour.

Path Parameters

  • chainId
    Type: integer
    required

    Integer numbers.

  • assetAddress
    Type: string
    required

Query Parameters

  • rulePreset
    Type: stringnullable

    Only count agents on this rule preset (e.g. explorative). Omit to count every preset.

Responses

  • 200
    Type: GetAssetApyStatsResponse

    Successful response

    • assetApyStats
      Type: AssetApyStats
      required
      Properties: 13
    application/json
Request Example for get/v1/chains/{chainId}/assets/{assetAddress}/apy-stats
curl '/v1/chains/1/assets/{assetAddress}/apy-stats'

{
  "assetApyStats": {
    "chainId": 1,
    "assetAddress": "string",
    "rulePreset": "string",
    "apyMoneyWeighted7d": 1,
    "apy25thPercentile7d": 1,
    "apyMedian7d": 1,
    "apy75thPercentile7d": 1,
    "expectedApy7d": 1,
    "apyMoneyWeighted30d": 1,
    "apy25thPercentile30d": 1,
    "apyMedian30d": 1,
    "apy75thPercentile30d": 1,
    "expectedApy30d": 1
  }
}

Successful response

getPlatformStats

Get platform statistics

​

Returns public aggregate statistics for the YieldSeeker platform, including users, agents, tracked value, earned yield, transaction volume, and active-agent APY percentiles.

Responses

  • 200
    Type: GetPlatformStatsResponse

    Successful response

    • agentCount
      Type: integer
      required

      Total number of agents across the platform.

    • apy75thPercentile
      Type: number
      required

      75th percentile APY across active agents, expressed as a percentage.

    • apyMax
      Type: number
      required

      Maximum APY across active agents, expressed as a percentage.

    • totalTransactionCount
      Type: integer
      required

      Total number of transactions executed by agents.

    • totalTransactionValueUsd
      Type: number
      required

      Total value of agent transactions, in USD.

    • totalTvlUsd
      Type: number
      required

      Total value currently tracked across agents, in USD.

    • totalYieldEarnedUsd
      Type: number
      required

      Cumulative yield earned across agents, in USD.

    • userCount
      Type: integer
      required

      Total number of registered users.

    application/json
Request Example for get/v1/platform-stats
curl /v1/platform-stats

{
  "userCount": 1,
  "agentCount": 1,
  "totalTvlUsd": 1,
  "totalYieldEarnedUsd": 1,
  "totalTransactionCount": 1,
  "totalTransactionValueUsd": 1,
  "apy75thPercentile": 1,
  "apyMax": 1
}

Successful response

Users (Collapsed)

​

Manage the human (or integrator end-user) behind the wallet: create an account, look up details, and update a username. A user can own multiple agents, so these endpoints sit above the per-agent resources below.

Users Operations

Agents (Collapsed)

​

The core of YieldSeeker: create an agent, deploy its dedicated smart wallet, and track everything it owns - live yield positions, portfolio snapshots, historic performance, and lifetime statistics. This is where you spin up a new autonomous yield-seeking wallet for a user and watch its performance over time, right through to deactivating it once its work is done.

Agents Operations

Agent Operations (Collapsed)

​

Everything that drives or steers an agent day-to-day. Chat with it directly, review its past allocation decisions, and shape future behavior with steering memories and effective rules. Also covers moving value: withdraw from a yield position, or get back unsigned deposit/withdrawal calldata (prepareDeposit / prepareWithdrawal) so a user can fund or defund the agent's wallet themselves, no backend signing required.

Agent Operations Operations

Share Cards (Collapsed)

​
Share Cards Operations
YieldSeeker Docs