API Reference

Quick-lookup tables — public surfaces, base URLs, asset IDs, chain IDs, status enums, error shapes, format conventions, message-status polling.

Quick-lookup tables for the constants you'll reference most. For the full operation-by-operation spec, see the live OpenAPI reference — every endpoint with full type info and code samples.

Public API surface — what to call, what to avoid

A consumer app talks to this allow-list of public surfaces:

Public surface
POST auth.yieldfabric.com/auth/** (REST)
For
Sign-in (/auth/login, /auth/signature/signin, /auth/api-key, /auth/<provider>/exchange), token refresh, /protected/jwt lookup, /auth/users/me, API-key issuance.
Public surface
GET pay.yieldfabric.com/api/users/{user_id}/messages/{message_id} (REST)
For
Message status polling for on-chain operations. Status flips from Pending / Validating / Executing to Completed / Failed / ManualSignature when executed is non-null.
Public surface
POST api.yieldfabric.com/graphql (GraphQL gateway)
For
All public GraphQL reads and mutations — entity lookups, walletFlow.activity, joined wallet / contract / payment listings, deal-flow reads, instant, deposit, withdraw, obligations, swaps, and composed payment operations. Same JWT.
Public surface
agents.yieldfabric.com (REST/SSE)
For
Working groups, threads, documents, pipelines, workflow streams, and agent conversation state when your app uses the AI collaboration surface.

Don't call these from app code:

Internal surface
POST pay.yieldfabric.com/api/mq/submit
Why
Internal service-to-service write path. Bypasses GraphQL resolver input normalisation, idempotency, and entity resolution. Requires a vault-equipped caller — consumer JWTs get 403 Insufficient permissions: CryptoOperations. Use the corresponding GraphQL gateway mutation instead.
Internal surface
GET pay.yieldfabric.com/api/chain/**
Why
Internal helper for resolving on-chain constants. The GraphQL resolvers already do this for you.
Internal surface
POST agents.yieldfabric.com/api/mcp/**
Why
LLM tool-call surface, not data flow.

Full rationale: Building with YieldFabric.

Base URLs

Substitute your deployment's URLs if different.

Service
Auth
Default
https://auth.yieldfabric.com
Service
Payments
Default
https://pay.yieldfabric.com
Service
Gateway (GraphQL)
Default
https://api.yieldfabric.com
Service
Agents
Default
https://agents.yieldfabric.com

Asset IDs

Asset ID
aud-token-asset
Description
Australian Dollars (example asset)
Asset ID
usd-token-asset
Description
US Dollars (example asset)

The IDs above are illustrative — the assets actually deployed are specific to each environment. Use the federated asset queries or deployment-provided config to enumerate what's available.

Chain IDs

Chain ID
151
Network
Redbelly Mainnet (Governors)
Chain ID
153
Network
Redbelly Testnet (Governors)

Don't hard-code chain addresses in browser code. Most mutations resolve chain constants server-side; if your backend truly needs deployment constants, load them from approved deployment config.

Error shapes

Surface
Auth REST (auth.yieldfabric.com)
Wire shape
Flat { "error": "<string>" } + HTTP status
How to route
Switch on HTTP status. The error string is human-readable and may change between releases.
Surface
GraphQL gateway (api.yieldfabric.com/graphql)
Wire shape
Usually HTTP 200 + errors[].extensions.code in envelope
How to route
Switch on extensions.code, not message.
Surface
Agents REST (agents.yieldfabric.com)
Wire shape
Same as auth (flat)
How to route
Same as auth.

Common HTTP status codes

Status
200 / 201 / 204
When you see it
Success.
Status
400
When you see it
Validation failed, idempotency conflict, business-rule violation. Check the response body for the specific code.
Status
401
When you see it
Missing / expired / wrong-audience JWT. Refresh or re-login.
Status
403
When you see it
JWT valid but role / scope lacks the permission. The classic is Insufficient permissions: CryptoOperations on vault-touching ops.
Status
404
When you see it
Resource doesn't exist — or is visibility-scoped to a group you're not a member of.
Status
422
When you see it
Validation error (input parameters).
Status
429
When you see it
Rate-limited (login failures only at the moment; response delayed but still 401).
Status
5xx
When you see it
Server-side; safe to retry with the same idempotencyKey.

GraphQL error codes you'll see most

Code
INSUFFICIENT_BALANCE
Meaning
The account doesn't have enough to fund the operation.
Code
IDEMPOTENCY_CONFLICT
Meaning
Same key used with a different request body.
Code
CONTRACT_STATE_INVALID
Meaning
Contract not in the right state for this transition.
Code
SWAP_STATE_INVALID
Meaning
Swap not in the right state for this transition.
Code
DEAL_STATE_INVALID
Meaning
Deal not in the right state for this transition.
Code
COUNTERPART_NOT_FOUND
Meaning
The destination party isn't resolvable.
Code
FORBIDDEN
Meaning
Caller lacks permission.

Message status (on-chain operations)

Long-running on-chain operations (deposit, send, swap, mint obligation) submit a message, return a messageId, then execute asynchronously. Poll GET /api/users/{user_id}/messages/{message_id} on the payments service (not the gateway):

Status
Pending
Meaning
In queue, not yet picked up by the validator.
Status
Validating
Meaning
Validator is checking balances, building unsigned tx.
Status
ManualSignature
Meaning
Waiting for the user to sign from their wallet UI.
Status
Executing
Meaning
Signed; on-chain submission in flight.
Status
Completed
Meaning
On-chain receipt landed. executed is non-null.
Status
Failed
Meaning
Did not settle; check response.error.

Terminal when executed is non-null. Poll at 2-second intervals, cap at 300s, then surface failure to the user.

Status enums

Payment status

Status
PENDING
Meaning
Submitted, not yet on-chain.
Status
PROCESSING
Meaning
On-chain execution in progress.
Status
COMPLETED
Meaning
Settled on-chain.
Status
FAILED
Meaning
Did not settle; check the message for the reason.

Contract status

Status
PENDING
Meaning
Created but not yet accepted by the counterparty.
Status
ACTIVE
Meaning
Accepted and in force.
Status
COMPLETED
Meaning
All payments settled. (For self-counterpart pure-agreement obligations, this is set in one message via the auto-accept fast path.)
Status
CANCELLED
Meaning
Terminated before completion.

Swap status

Status
PENDING
Meaning
createSwap landed; awaiting completeSwap.
Status
ACTIVE
Meaning
completeSwap settled; repurchase window open (if any).
Status
COMPLETED
Meaning
One-shot exchange finished.
Status
REPURCHASED
Meaning
repurchaseSwap settled; collateral returned.
Status
CANCELLED
Meaning
cancelSwap landed before completion.
Status
EXPIRED
Meaning
Expiry passed but expireCollateral not yet called.
Status
FORFEITED
Meaning
expireCollateral settled; collateral transferred.

Deal status

See the DMS guide for the full state machine. Briefly: Draft → Proposed → Accepted → Active → Completed with CounterOffered / Rejected / Cancelled / Defaulted / FailedAfterPartialExecution detours.

Format conventions

Amounts — integer strings, no decimals.

✓
"100"
✗
100 (must be a string)
✓
"100"
✗
"100.00" (no decimal points)

Timestamps — ISO 8601.

✓
"2026-11-01T00:00:00+00:00"
Notes
Full RFC 3339
✓
"2026-11-01"
Notes
Date-only is also accepted

Wallet IDs — UUIDv4 (canonical). Resolve from /protected/jwt (default_wallet_id claim) or entitiesByName queries on the federation gateway.

Idempotency keys — omit the field or pass a fresh UUIDv4 for each submission.

  • Same key + same body = same response (no double-execution).
  • Same key + different body = 400 IDEMPOTENCY_CONFLICT.
  • Generate as a fresh UUIDv4 per submission when you provide one. Never deterministic (sha256(user || action) is the classic foot-gun — a retry after a stuck message returns the stuck messageId again without re-enqueueing).
YieldFabric docs(317)