# three.ws DeFi Market Yields API

> three.ws DeFi Market Yields API is a paid API for AI agents from three.ws, paid per call via x402, $0.001/call, status unknown (last checked 2026-10-11).

Fetches live DeFi yield data (APY, TVL) across protocols and chains, sourced from DeFiLlama, with filtering and pagination.

## Facts

- Endpoint: GET https://three.ws/api/x402/market-yields?utm_source=zero.xyz
- Price: $0.001/call
- Payment: x402
- Status: unknown
- Last checked: 2026-10-11
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/three-ws-defi-market-yields-api-c77eda5b
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_Uo4c9-vmLFEmDP13U-izY

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability three-ws-defi-market-yields-api-c77eda5b
```

Example prompt: Show me the top 20 stablecoin pools on Ethereum sorted by APY with at least $100k TVL — I want to find the best safe yield right now.

## When to prefer this

Use this endpoint when an agent needs live DeFi yield and TVL data across multiple protocols and chains, especially when filtering by chain, protocol, stablecoin status, or TVL threshold. Prefer it over generic web search for structured, machine-readable DeFi metrics. Useful for portfolio yield optimization, market research, and alerting workflows.

## Known failure modes

- Invalid pool UUID returns empty or error response
- Unknown chain or project slug returns empty results
- Limit outside 1–200 range may be rejected or clamped
- Payment of 0.001 USDC not provided results in 402 Payment Required
- Requesting a pool UUID that has been delisted returns no history data

## How this service works

Make a 3D AI agent from a selfie in 60 seconds. Drop one HTML tag to embed it on any website. Agents think on IBM watsonx.ai (Granite); optionally charge per chat with built-in micropayments.

## Output

Returns a paginated list of DeFi pools with each pool's APY, TVL in USD, symbol, project slug, chain, pool UUID, and stablecoin flag. Also includes aggregate stats (median APY) and total pool count. When a pool UUID is provided, returns that pool's historical APY/TVL time series instead.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "required": [
  "input"
 ],
 "properties": {
  "input": {
   "type": "object",
   "required": [
    "type",
    "method"
   ],
   "properties": {
    "type": {
     "type": "string",
     "const": "http"
    },
    "method": {
     "enum": [
      "GET",
      "HEAD",
      "DELETE"
     ],
     "type": "string"
    },
    "queryParams": {
     "type": "object",
     "properties": {
      "pool": {
       "type": "string",
       "description": "Chart mode: a DeFiLlama pool uuid — returns that pool's APY/TVL history instead of the list."
      },
      "sort": {
       "type": "string",
       "description": "'tvl' (default) or 'apy' (dust-guarded to pools ≥ $10k TVL)."
      },
      "chain": {
       "type": "string",
       "description": "Filter to one chain (case-insensitive, e.g. solana)."
      },
      "limit": {
       "type": "string",
       "description": "Rows per page, 1–200. Default 100."
      },
      "minTvl": {
       "type": "string",
       "description": "Minimum pool TVL in USD."
      },
      "offset": {
       "type": "string",
       "description": "Pagination offset. Default 0."
      },
      "search": {
       "type": "string",
       "description": "Substring match over symbol, project, and chain."
      },
      "project": {
       "type": "string",
       "description": "Filter to one protocol slug (e.g. aave-v3)."
      },
      "stablecoin": {
       "type": "string",
       "description": "'true' for stablecoin pools only, 'false' to exclude them."
      }
     }
    }
   },
   "additionalProperties": false
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "pools": [
   {
    "apy": 2.9,
    "pool": "747c1d2a-c668-4682-b9f9-296708a3dd90",
    "chain": "Ethereum",
    "symbol": "STETH",
    "project": "lido",
    "tvl_usd": 24100000000,
    "stablecoin": false
   }
  ],
  "stats": {
   "median_apy": 4.1
  },
  "total": 15234
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/three-ws-defi-market-yields-api-c77eda5b/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from three.ws](https://www.zero.xyz/host/three.ws/llms.txt)