TRDEFI Liquidity API

Public, read-first API over the live non-custodial liquidity catalogue — and a prepare-only write path for integrators holding a key, or paying per request with x402.

v1 base: https://yield.trdefi.com the API never signs

Endpoints

Response shape

Read endpoints return { data, meta }. The meta block is where freshness lives:

{
  "data": { "totals": { "strategies": <int>, "volume_30d_usd": <number>, … }, … },
  "meta": {
    "requestId": "<hex string>…",
    "generatedAt": "2026-09-24T02:11:05.376Z",
    "apiVersion": "v1",
    "freshnessSeconds": 10800,
    "cached": false
  }
}

Authentication

The read surface above needs no key. It is rate-limited and the limits are advertised in the headers of every reply.

The write path is prepare-only

Creating a position needs a key. The API never signs and never broadcasts. It returns the complete set of unsigned transactions, and your own wallet signs them from your own address. There is no signing grant, no delegated key, and no moment at which a credential of ours can move value.

POST /v1/positions
Authorization: Bearer trd_live_<keyId>_<secret>
Idempotency-Key: 8f14e45f-ea2b-4c1a-9b3e-1d2c3b4a5f60

{
  "chain": "arc",
  "wallet": "0xYourOwnWalletThatWillSign",
  "deposits": [
    { "symbol": "USDC", "amount": "1000000" },
    { "symbol": "EURC", "amount": "900000" }
  ],
  "makerFeeBps": 30000,
  "checkBalances": true
}

← 200 { data: {
          status: "prepared",            ← nothing has happened yet
          strategyHash: "0x9f71222e…",   ← identity of the position
          transactions: [ {step, purpose, to, value, data, description}, … ],
          fee: { protocolFeePercent: "0.05", removable: false },
          preflight: { status: "ready", checks: [ … ] }
        } }

You supply both amounts, so we never have to guess a price. The approve steps appear only where your live allowance is short — so the same position can come back as one transaction or three. Sign them in order with your own wallet, then broadcast. Add an Idempotency-Key and a retry returns the same strategyHash instead of creating a second position.

A key is always trd_live_<keyId>_<secret> (or trd_test_… for test networks), held server-side only — a key in client-side code is treated as compromised. Keys are scoped, origin-restricted and revocable at any time. Request one here.

The write path also takes x402 — no key

A caller with no key can instead pay per request with x402. Call POST /v1/positions (or /v1/swaps) with no credential and the route answers 402 Payment Required with the payment terms (x402Version: 2, an accepts[] list, and a bazaar extension — the same JSON base64-encoded in the PAYMENT-REQUIRED header). Two rails: Base USDC (eip155:8453, settled by Coinbase's CDP facilitator) and Arc USDC (eip155:5042, settled by our own). The fee is a flat 0.02 USDC per request — additional to, and separate from, the 0.05 % protocol fee inside the position.

Pay with your own wallet and retry the same call with the encoded payment in a PAYMENT-SIGNATURE header (x402 v2; the deprecated v1 X-PAYMENT is still accepted); the reply carries meta.payment and a PAYMENT-RESPONSE header. A refused payment returns 402 PAYMENT_INVALID (never a fresh challenge, which would invite a double payment). A position prepared this way has no key and is not visible through the key-scoped GET /v1/positions/<hash>.

The two demo endpoints back the public test-network demo and are additionally restricted to TRDEFI's own pages (Origin/Referer). They are not general-purpose APIs and carry a tighter limit.

For agents. The read surface is also exposed as a remote MCP server at /mcp — ten keyless tools, all prefixed trdefi_: trdefi_stats, trdefi_chains, trdefi_positions, trdefi_position_detail, trdefi_position_inventory, trdefi_quote, trdefi_fusion_quote, trdefi_fusion_prepare, trdefi_fusion_submit, trdefi_badge, so an agent can call the catalogue without writing HTTP. Transport: JSON-RPC 2.0 over POST — there is no browsable page at that path, so a browser GET returns 405 with "Use POST for the MCP endpoint.". That is expected; connect it as an MCP client.

In Replit Agent? Add it with one click: replit.com/integrations.

Rate limits

Limits are per path bucket and per credential. Read buckets are per client, so issuing more keys does not raise them; the prepare bucket is per key. Splitting one integration across many keys to raise an effective ceiling is a breach of the acceptable-use rules — ask for a raised bucket instead.

Read the numbers from the response, not from this table — the headers are authoritative and may change before this page does:

curl -sD - -o /dev/null https://yield.trdefi.com/api/stats | grep -i ratelimit
ratelimit-limit: 120
ratelimit-remaining: 119
ratelimit-reset: 42
ratelimit-policy: stats;w=60;limit=120

On 429, Retry-After is always present. The limit resets on a fixed window.

Error codes

Branch on code, never on message. retryable is part of the contract.

Envelope

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded for stats",
    "requestId": "<hex string, echoed per request>",
    "retryable": true,
    "documentation": "https://yield.trdefi.com/docs/api/errors#rate_limited"
  }
}

Client-fixable problems (an allowance too low, a balance too low, an unsupported chain) additionally carry a structured issues[] array with expected / actual, so you can correct them without contacting us.

Versioning & deprecation

Try it

# totals
curl -s https://yield.trdefi.com/api/stats | head -c 400

# which chains are live
curl -s https://yield.trdefi.com/api/chains

# a README badge
curl -s "https://yield.trdefi.com/api/badge?metric=volume30"

Listings

Where this API is indexed, and what a third party has actually verified by paying for it.

Agents can search the PayAPI marketplace at https://payapi.market/mcp:

{ "mcpServers": { "payapi": { "url": "https://payapi.market/mcp" } } }

Request API access

Reading needs no key. To create positions through the API you need a key, and keys are issued after a short review — we need to know who you are, what you are building, and roughly what volume to expect. (If you would rather not hold a key, the same routes accept an x402 payment — pay-per-request, no account.)