Versioning

Every Yieldforce B2B endpoint lives under the /v1/ URL prefix. Breaking changes that cannot be added backward-compatibly result in a new /v2/ prefix — not a header change.

URL prefix

The version is part of the path, not a header:

GET  /v1/partner/pools
POST /v1/partner/end_users
POST /v1/partner/end_users/{external_id}/deposit
POST /v1/partner/end_users/{external_id}/withdraw

This makes the version visible in every URL, every log line, and every network trace. There is no version header to negotiate — the URL is the contract.

Backward-compatible changes within v1

The following changes may ship within /v1/ without notice:

• New optional response fields (existing fields are never removed or renamed)
• New optional request fields (existing required fields stay required)
• New endpoints
• New error code values that are subclasses of existing error categories
• New query parameters with defaults that preserve current behavior

Your client must tolerate unknown fields in responses (do not use strict deserialization that rejects extra fields).

Breaking changes → /v2/

A change is breaking if it:

• Removes or renames an existing field
• Changes a field's type or nullability
• Changes a previously optional field to required
• Changes the semantics of an existing error code
• Removes an endpoint

When a breaking change is necessary, Yieldforce cuts /v2/. Both /v1/ and /v2/ are served in parallel for a minimum of 12 months. A migration guide ships before the deprecation period begins.

Deprecation policy

To be defined when the first deprecation lands. Will follow industry-standard Sunset and Deprecation headers per RFC 8594. Partners on affected endpoints will be notified by email before the sunset date.

X-Yieldforce-Api-Version response header

Every response includes this header:

X-Yieldforce-Api-Version: 1.0.0

It reflects the API version that served the request. Include it in support tickets alongside X-Yieldforce-Request-Id — both together let the team pinpoint the exact server version and request.

Webhooks (deferred)

Why deferred

• Synchronous HTTP works for money flows. Deposit and withdraw endpoints hold the HTTP connection open until the on-chain transaction lands (typically 5–30s on Base). The response carries the transaction hash and updated state. No async delivery needed.
• No partner-side infrastructure required. Webhooks require a publicly-reachable HTTPS endpoint with a stable identity and the ability to receive and verify signed POST requests. Long-lived sync HTTP requires nothing extra.
• Retry, signature, and idempotency semantics add complexity. HMAC signing schemes, replay protection, exponential backoff retry windows, dead-letter queues, and secret rotation are all non-trivial — and deferrable when sync HTTP suffices.

Replacement pattern

Use synchronous HTTP for the operations that would otherwise have webhooks:

1. Call POST /v1/partner/end_users/{external_id}/deposit or .../withdraw with a timeout of at least 60 seconds.
2. The response returns when the on-chain transaction is confirmed. Parse the transaction hash and updated balances directly.
3. If your connection drops mid-flight, the on-chain transaction is still being processed. Recover by polling GET /v1/partner/end_users/{external_id}/transactions until the transaction appears.
4. Use the original Idempotency-Key when retrying — the server will return the cached response if the operation already completed.

When this might change

Webhooks may be revisited if any of the following become true:

• A partner needs real-time dashboard updates (push instead of pull) and polling is insufficient.
• A long-running off-ramp or fiat rail requires genuinely async delivery (async by nature of the rail, not just latency).
• Three or more partners explicitly request webhook support as a precondition for their integration.
• Yieldforce moves to a slower-finality chain where transaction confirmation takes minutes rather than seconds, making long-lived sync HTTP impractical.