Version: 1.1 · Effective: 2026-09-25 · Applies to: https://yield.trdefi.com/api/ and https://yield.trdefi.com/v1/

The operating rules that apply to every client of the API. Read together with the Method of Statement (what the API is) and the Overall Scheme (the endpoints and the write path).

---

1 · Authentication and credentials

Surface	Credential	Notes
Read surface (GET /api/*)	None	Open. Rate-limited, and the limit is advertised on every reply.
Write path (POST /v1/positions)	One API key, held server-side by the client	The key prepares unsigned transactions. It cannot sign, broadcast or move value.

There is no signing grant. That is the point of the design. A signing grant would be a secret of ours that can move a client's money; instead the client signs with its own wallet and we never hold anything worth stealing. A leaked API key costs its owner a rate-limit abuse problem — never a token.

Key format

trd_live_<keyId>_<secret>

• keyId — a short public identifier. Safe to log; it is what appears in our audit trail.
• secret — shown once, at issuance. We store only sha256(secret + salt) and cannot recover it.
• Send it as Authorization: Bearer trd_live_<keyId>_<secret>.
• A key issued for test networks is prefixed trd_test_ instead of trd_live_.

Getting a key

Request one at https://yield.trdefi.com/docs/api#access. Tell us who you are, what you are building and roughly what volume to expect. Keys are issued after a short manual review — we will not give a write key to an address we cannot reach. There is no self-service issuance, and no key is needed to read.

Scopes

Every key carries an explicit set of scopes. A request outside its scopes is refused with 403.

Scope	Grants
read	Read the public catalogue. Not needed — the read surface is open — but a key that has it may be used to carry the read quota on the same credential.
prepare	POST /v1/positions. The only scope that writes anything, and even it only prepares.
admin	Manage the organisation's own keys and webhooks. Not granted on request; issued per organisation.

A key with prepare alone cannot read the catalogue. A key with read alone cannot prepare. Request only what the integration needs.

Rules that apply to any key we issue

1. Server-side only. Never in a browser. A key in client-side code is treated as compromised.
2. Scoped. Bound to an organisation and to the scopes listed above.
3. Origin-restricted. Write requests from an origin that is not on the key's allowlist are refused.
4. Revocable at any time. Revocation takes effect immediately; a revoked key is refused on its next request.
5. Rotatable without downtime. A client may hold two valid keys during a rotation window.
6. We never ask for a wallet key. No endpoint, ever, accepts a private key or seed phrase.
7. Never share a key between environments. A test key and a live key are different credentials.

2 · Environments

Environment	Base URL	Purpose
Production	https://yield.trdefi.com/api, https://yield.trdefi.com/v1	Live data, live positions
Test	public test networks (trd_test_ keys)	Verifying integration code before pointing at production

Read-side behaviour is identical across environments. A client should verify against the test environment first; writing integration code that only works in production is not supported. A live key refuses a test-network chain and a test key refuses a mainnet one.

3 · Request and response conventions

• Method. Read endpoints accept GET. POST is accepted only on the write path. OPTIONS is answered for CORS preflight. Anything else returns 405 METHOD_NOT_ALLOWED.
• Content type. application/json; charset=utf-8.
• Identifiers. Every response carries X-Request-Id. Quote it in any support request. The same id is echoed in the body of the reply.
• Amounts. Monetary values in read models are returned in USD as numbers. On-chain amounts are strings in base units with an explicit decimals — never parse them as floats. The write path takes amounts the same way: an integer string in base units, with the token's decimals resolved server-side from the live token registry, so a 6-decimal and an 18-decimal token can never be confused.
• Timestamps. ISO-8601, UTC.
• Unknown fields. New fields may appear at any time. Ignore what you do not recognise; do not fail on it.
• Caching. We send Cache-Control. meta.cached tells you whether the reply was served from our short-lived cache. Clients are free to cache within the advertised window.

4 · Rate limits

Limits are enforced per credential and per bucket. Issuing more credentials does not raise them.

Bucket	Limit	Window
stats	120	60 s
badge	120	60 s
chains	60	60 s
quote	60	60 s
strategy-detail	60	60 s
strategies	20	60 s
prepare (POST /v1/positions)	agreed per key, default 6	60 s

The headers are authoritative, not this table. Every reply carries:

RateLimit-Limit: 120
RateLimit-Remaining: 119
RateLimit-Reset: 42
RateLimit-Policy: stats;w=60;limit=120

• The window is fixed and resets in RateLimit-Reset seconds.
• On 429, Retry-After is always present. Honour it.
• Do not retry a 429 without backoff, and do not fan a single logical operation across many parallel requests to stay under the limit. Doing so is a breach of §10.
• Limits may be tightened. When they are, the headers change — they are never silently reduced without the RateLimit-Policy value reflecting it.
• A key's limits are per key, not per organisation. Splitting one integration across ten keys to raise the ceiling is a breach of §10. Request a raised bucket instead.

5 · Idempotency and retries

• Writes. Any state-changing call accepts an Idempotency-Key header. A repeated request with the same key returns the original outcome rather than performing the action twice. Keys are retained for 24 hours.
• POST /v1/positions is idempotent by construction. Nothing is broadcast, so repeating a preparation is harmless. The salt is derived from (your key, Idempotency-Key), so the same key returns the same strategyHash and cannot create a second position. Use a new key to prepare a genuinely new position; omit the header entirely and every call creates one.
• Retryable failures. A response is safe to retry when error.retryable is true, or when no response was received at all. Use exponential backoff with jitter.
• 5xx on a write consumes the key — the operation may or may not have been applied. Retry with the same key to get a definitive answer. Do not generate a fresh key for a retry.
• Do not retry a 4xx other than 429. Correct the request first.
• Reads are naturally idempotent; retry freely within the limit.

6 · Errors

Every error uses one envelope:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded for stats",
    "requestId": "9f2c1d4e7a8b3c5d6e0f1a2b3c4d5e6f",
    "retryable": true,
    "documentation": "https://yield.trdefi.com/docs/api#rate_limited"
  }
}

• Branch on code, never on message. Messages are for humans and may change at any time.
• Honour retryable. It is part of the contract.
• Client-fixable problems additionally carry a structured issues[] array with expected and actual values — an allowance that is too low, a balance that is too low, a chain that is not live, an expired preparation — so a client can correct the condition without contacting us.
• Authentication codes (401, 403) never say whether a key exists. A wrong key and a revoked key return the same envelope.
• The full code table lives at https://yield.trdefi.com/docs/api#errors.

7 · Signature and broadcast are the client's

The write path returns unsigned transactions. Two consequences a client must accept:

• We cannot retry a broadcast for you. Only the holder of the wallet can sign. If a signed transaction fails, re-prepare and ask the wallet again.
• A prepared transaction is not a reservation. It is a computation of what must be signed. It does not hold liquidity, is not binding on anyone, and expires the moment the allowance it references changes. Re-prepare whenever you like — that is what the endpoint is for.

8 · Webhooks

Where a client subscribes to events, the following rules apply.

• Delivery is at-least-once. A client may receive the same event more than once; deduplicate on the event id.
• Every delivery is signed. Verify the signature before acting on the payload. A client that does not verify a signature is accepting unauthenticated instructions.
• Retries follow a published, bounded backoff ladder. A client may replay a missed window by fetching the affected resource directly — the API is the source of truth, not the webhook.
• Ordering is not guaranteed. Use the event timestamp and the resource state, not arrival order.
• Reorganisations are events. A chain reorganisation that changes a recorded outcome produces a correction event; clients should treat it as an ordinary update, not an error.
• A client's endpoint must be idempotent and fast. Slow handlers are retried, not queued indefinitely.

9 · Versioning and deprecation

• Resources are path-versioned. /api/ and /v1/ are the current contract.
• Additive changes are not breaking and may ship at any time: a new response field, a new endpoint, a new enum value, a new error code. Clients must tolerate unknown fields and unknown enum values.
• Breaking changes — a field removed or renamed, a type or meaning changed, an endpoint removed — ship under a new path version with a minimum 90 days' notice on the public calendar, and a documented replacement.
• Nothing is removed without a replacement. There is no equivalent of a bare 410 Gone in this contract.
• A client may run two versions side by side during a migration. We publish a compatibility test suite so a client can prove its integration before switching.

10 · Acceptable use

A client must not:

• attempt to exceed, circumvent or disguise traffic in order to bypass a rate limit
• split one integration across multiple keys to raise an effective ceiling
• resell or redistribute the API as a competing data service without a written agreement
• present a prepared position as an executed one, or a prepared transaction as a settled trade
• scrape the read surface to reconstruct bulk datasets where a documented endpoint does not exist for that purpose
• probe, fuzz or load-test production without a pre-agreed window
• use the data to make a claim about TRDEFI, or about any third party, that the data does not support
• use the API where doing so would breach the client's own regulatory obligations

A client must:

• keep credentials server-side and rotate them when staff or systems change
• handle 429 and 5xx with backoff rather than retry storms
• verify any figure independently before making a financial decision on it
• contact us before a large integration or a migration, not after

11 · Request logging and auditing

We record one row per API request so we can operate the service and measure the service level we publish. This is what is stored:

Field	Stored as
Path, method, HTTP status, latency	as observed
Timestamp	UTC
Client IP address	sha256(ip + salt) — the raw address is never stored
Country	coarse, derived from the request
User agent	truncated to 200 characters
Origin / referer	truncated to 200 characters
API credential id	the keyId portion only — never the secret

We do not store request bodies, query-string values, cookies, or any account data. Rows are deleted after 30 days. IPs are hashed precisely so that we can count distinct clients without holding personal data.

What a client can audit about itself: every call made with its key is attributable to the keyId in our log. Revoke a key and the abuse stops; the record of what it did remains for the retention window. That is the audit trail — it is per key, and it is why a shared key is a bad idea.

Aggregates may be used internally for capacity and SLO measurement, and may be published only in aggregate form that cannot identify a client.

12 · Fees

A position created through TRDEFI — web app or API — carries a 0.05 % protocol fee embedded in the signed order data. It is not a separate transfer and not an invoice; it executes on-chain with the position. There is no tier and no parameter that waives it, and the integrator cannot remove it.

The integrator's own commission (makerFeeBps) is theirs to set and is independent of it. Full statement: Overall Scheme, Part 7.

13 · Support

Channel	Use
info@trdefi.com	Anything, including integration questions and key requests
requestId in the error envelope	Always include it — it lets us find the exact call

Include, in every support request: the X-Request-Id, the endpoint, the exact request (redact any credential), and the response body as received.

14 · Changes to these rules

These rules may be updated. A change that materially affects an existing integration is announced with the same 90-day notice as a breaking API change. The current version is always published at

https://yield.trdefi.com/docs/general-rules with an effective date.

---

TRDEFI Ltd, London, United Kingdom. See also: Method of Statement, Overall Scheme.