Yokefellow - Builder Docs
API Reference
The route-level API reference for the /api/sdk/v1 surface, request conventions, response shapes, and lifecycle helpers.
1. What This Reference Is
The Yokefellow API Reference is the direct lookup guide for the platformâs integration surface. It explains the read and write interface in route-level terms: what kinds of objects the API exposes, how requests are shaped, how responses are returned, how lifecycle-driven actions are tracked, and how failures should be handled. This document is for builders who need the raw programmatic surface in reference form rather than only the packaged client view.
This reference belongs inside the Developer Docs Hub alongside the Quickstart, SDK Guide, Integration Playbook, and Example App Spec. Those documents do different jobs. The Quickstart is the smallest path to first successful integration. The SDK Guide explains the packaged client and the builder-facing lifecycle model. This reference sits underneath that layer and describes the underlying integration surface directly.
This document should be read as a reference, not as a product thesis. It does not restate the Whitepaper, explain the full operating model of the platform, or reframe the user meaning of rights and offerings. Those responsibilities belong elsewhere in the launch set. The purpose of this reference is narrower and more practical: help builders look up routes, understand request and response patterns, and implement correctly against the real Yokefellow surface.
2. How to Use This Reference
Use this document when you already know that you want direct API behavior rather than only the packaged SDK path. Some builders will arrive here after the Quickstart because they want the smallest path to a first successful read and write before going deeper. Others will arrive here after the SDK Guide because they want to see the route-level surface that sits underneath the client methods. Both paths are valid.
The cleanest reading order depends on the kind of work you are doing. If the goal is first successful integration with the fewest moving parts, start with the Quickstart. If the goal is to use the intended packaged client surface, start with the SDK Guide. If the goal is direct endpoint lookup, request-shape clarity, response-shape clarity, or lifecycle-step clarity, start here. Once the route-level behavior is clear, move to the Integration Playbook for product wiring decisions or to the Example App Spec for one full reference implementation.
This reference is organized around how builders actually work with the platform. It first defines the base route, auth posture, and request conventions. It then groups the API by read families, write families, lifecycle handling, returned objects, and errors. That mirrors the way the SDK Guide already groups the current client surface: bucket-facing reads, wallet-facing reads, request and lifecycle reads, queue reads, market reads, activity reads, funding writes, offering writes, and lifecycle completion. The goal is consistency. A builder should not have to learn one mental model for the SDK and a different one for the direct API surface.
When using this reference, treat lifecycle-driven actions as real multi-step flows rather than as one-shot requests. A successful request is not always the end of the action. Deposits, withdraws, transfers, and other tracked flows may require follow-up status checks or explicit finalization before the result should be treated as complete. That distinction is part of the integration surface itself, not an optional implementation detail.
3. Base Route and Versioning
The current Yokefellow integration surface is exposed through the SDK route family under:
/api/sdk/v1
In practice, builders will usually work against a fully qualified base URL such as:
https://your-domain.com/api/sdk/v1
This is the same route family used throughout the current Quickstart and SDK Guide examples. Public reads, app-auth reads, writes, transaction status checks, and finalization flows all sit underneath this versioned base path.
The v1 segment should be read as the version boundary for the current documented integration surface. Builders should target the full versioned path rather than assuming the site root or an unversioned API path. That keeps the integration anchored to the surface the documentation is actually describing. This reference documents the current v1 family rather than speculative future versions.
A normal direct request therefore begins from the versioned base and extends into a route family such as a bucket read, a wallet-linked read, a queue read, or a write action. For example, a bucket catalog read begins from the same base route the current Quickstart uses:
GET https://your-domain.com/api/sdk/v1/buckets/:bucketId/catalog
That route-level pattern matters because the API surface is grouped around Yokefellow primitives and flows rather than around generic service categories. Buckets, offerings, entitlements, queues, activity, market state, and transaction lifecycle all sit underneath the same versioned family.
Quick route map
This page is easier to scan when the route families are separated up front:
Public-first reads
GET /api/sdk/v1/buckets/:bucketId/catalog GET /api/sdk/v1/buckets/:bucketId/funding GET /api/sdk/v1/wallets/:wallet/entitlements GET /api/sdk/v1/market/orderbook GET /api/sdk/v1/activity/recent
Authenticated recognition read
GET /api/sdk/v1/apps/session
Strictly gated operator and participation routes
POST /api/sdk/v1/buckets/:bucketId/offering-requests PATCH /api/sdk/v1/buckets/:bucketId/offering-requests POST /api/sdk/v1/buckets/:bucketId/offerings/buy POST /api/sdk/v1/buckets/:bucketId/offerings/craft POST /api/sdk/v1/buckets/:bucketId/offerings GET /api/sdk/v1/buckets/:bucketId/capability-actions POST /api/sdk/v1/buckets/:bucketId/capability-actions GET /api/sdk/v1/queues/requests GET /api/sdk/v1/queues/mint POST /api/sdk/v1/queues/mint
Lifecycle helpers
POST /api/sdk/v1/funding/deposit POST /api/sdk/v1/funding/withdraw POST /api/sdk/v1/funding/transfer-between-buckets GET /api/sdk/v1/tx/status POST /api/sdk/v1/tx/status POST /api/sdk/v1/tx/finalize
4. Auth Model
The current Yokefellow API surface has three distinct concepts that builders must keep separate: request authentication, public-versus-app-scoped route access, and wallet context. These concepts are related, but they are not interchangeable. Confusing them leads to incorrect integrations and misleading assumptions about what a request is actually proving.
4.1 Request authentication
At the request-auth layer, the current surface supports two main auth inputs:
bearer token
app key
When a bearer token is present, requests are authenticated with the standard bearer header:
Authorization: Bearer <token>
When no bearer token is present but an app key is present, requests use the Yokefellow app-key header:
x-yf-app-key: <appKey>
This is the same auth order described in the current SDK Guide. Bearer auth takes precedence when available. App-key auth is the normal controlled-access model where bearer auth is not being used. If neither auth input is present, the request is sent without an auth header and will only succeed on routes that are intentionally public.
4.2 Public reads versus app-auth reads
Not every route in the current surface uses the same auth posture. Some reads are intentionally public and can be used without an app-auth header. Examples include bucket-facing reads, wallet-entitlement reads, market reads, YES pricing stats, and activity reads. These routes are meant to let builders prove route reachability before proving authenticated integration recognition.
By contrast, the routes that are strictly auth-gated in the current implementation are the routes built around integration recognition, offering participation state change, operator work, or bucket-controlled configuration. In practice, that includes app session, offering-request reads and writes, buy and craft writes, queue routes, capability-action routes, and bucket-level offering configuration routes.
Some funding and transaction-lifecycle helpers sit in between those two categories. In the current repo, deposit, withdraw, transfer-between-buckets, tx status, and tx finalize can be called without the same hard auth gate, even though recognized auth may still be accepted and reflected in returned fields such as requestedBy. Builders should therefore distinguish between public reads, strictly gated routes, and lifecycle helpers rather than assuming one auth rule applies to the whole surface.
A practical rule is simple: a successful public read proves that the route is reachable. A successful app-session read proves that the integration is recognized correctly. A successful lifecycle helper call does not, by itself, prove that the whole integration is on an authenticated route.
4.3 Wallet context
Wallet context is separate from request authentication. Request authentication identifies the app or integration that is making the call. Wallet context identifies the wallet address the read or action is about. A request can therefore be properly authenticated and still require an explicit wallet parameter because the API needs to know which user-side state is being inspected or changed.
This distinction appears throughout the current surface. Bucket reads may accept wallet context to return wallet-aware state for the same bucket. Offering requests require the wallet the participation action belongs to. Deposit, withdraw, and transfer flows also require wallet-linked context because the action is not only app-scoped. It is also tied to a participant or owner-side identity inside the Yokefellow flow.
A builder should therefore read auth and wallet like this:
auth identifies the integration
wallet identifies the user-side context of the read or action
That rule should remain stable across the rest of this reference.
4.4 Signing boundary
The API surface does not replace wallet signing. For chain-backed flows, the API prepares, tracks, and sometimes finalizes the Yokefellow-side lifecycle around the action, but the actual wallet-side signature or transaction submission still belongs to the wallet or chain layer used by the integration. This is most visible in deposit, withdraw, and transfer-between-buckets flows.
A builder should therefore treat auth, wallet context, and signing as three separate layers:
request authentication proves the integration can access the route
wallet context tells Yokefellow which wallet the state or action is about
wallet signing or transaction submission completes the chain-side part of the flow where required
That boundary matters because many lifecycle-driven actions are only understandable when these layers stay separate. A deposit is not complete just because the request was authenticated. A withdraw is not complete just because the wallet is known. A transfer is not complete just because the route returned a prepare response. The chain-side step and the Yokefellow-side lifecycle step still have to be handled correctly.
4.5 Practical auth rule
The simplest way to approach the auth model is this:
Use a public read first if you only need to prove route reachability. Use an app-session read when you need to prove authenticated integration recognition. Treat wallet context as separate from auth. Treat funding and tx helpers as lifecycle surfaces that may accept calls without the same hard auth gate as session or operator routes. Do not confuse app authentication with wallet identity or with wallet signing.
That rule matches the current repo surface more closely than a blanket statement that every write or lifecycle helper is app-scoped.
5. Request Conventions
The current Yokefellow API surface uses a small set of repeating request patterns. Builders should read those patterns before treating individual routes as isolated endpoints. The same conventions appear across bucket reads, wallet-linked reads, queue reads, funding flows, offering participation flows, and transaction lifecycle helpers.
At a high level, the current v1 surface uses four common request shapes:
path-parameter reads
query-shaped reads
JSON-body writes
lifecycle follow-up requests
Path-parameter reads are used when the route is centered on one primary object. Bucket routes, wallet routes, class routes, collection routes, and mint routes all follow this pattern. A bucket catalog read, for example, is shaped around the bucket identifier in the path rather than being modeled as a broad search surface. This matches the Quickstartâs direct API example and the SDK Guideâs bucket-centered reading model.
GET /api/sdk/v1/buckets/:bucketId/catalog GET /api/sdk/v1/wallets/:wallet/entitlements GET /api/sdk/v1/classes/:classId GET /api/sdk/v1/collections/:collectionId GET /api/sdk/v1/mints/:mintId
Query-shaped reads are used when the route needs optional filters rather than a single path-only lookup. In the current surface, this appears most clearly in wallet-aware bucket reads, request-history reads, queue reads, market reads, activity reads, and transaction status reads. The SDK Guide already describes several of these query families, including wallet, round, limit, status, id, and transaction identifiers.
Common current query fields include:
wallet
round
bucketId
offeringId
includePending
id
status
limit
window
txHash
kind
chainId
fromBucketId
toBucketId
JSON-body writes are used for state-changing actions. The current implementation uses JSON request bodies for funding preparation, withdraw submission, transfer preparation, offering-request creation, offering-request resolution, buy flows, craft flows, queue execution, and transaction finalization. This matches the Hubâs framing of the API Reference as the place for write APIs, request patterns, and object groupings.
The current write surface is centered on bodies like these:
{ "bucketId": "<uuid>", "wallet": "0x...", "amountYesRaw": "1000000000000000000" }
{ "offeringId": "<uuid>", "wallet": "0x...", "qty": 1, "selectedOutputId": null }
{ "kind": "deposit", "bucketId": "<uuid>", "wallet": "0x...", "txHash": "0x..." }
Lifecycle follow-up requests are an important part of the surface. A builder should not assume that every successful POST means the full action is complete. In the current funding and transaction model, a prepare request can return the next required step, a status route, and a finalization route. That is consistent with the SDK Guideâs explanation that deposit, withdraw, and transfer-between-buckets are lifecycle-driven rather than one-shot actions.
The core identifier conventions in the current route family are also stable:
bucket ids are UUIDs
offering ids are UUIDs
class ids are UUIDs
collection ids are UUIDs
request ids are UUIDs
wallet addresses are 0x addresses
transaction hashes are 0x hashes
raw YES amounts are decimal integer strings
That matches the current validation layer used across the implemented routes, where UUIDs, addresses, tx hashes, integers, and unsigned integer strings are validated before route logic runs.
A practical rule for builders is simple: read the path for the primary object, read the query for filters and wallet context, read the JSON body for state-changing input, and read the returned lifecycle fields before deciding whether the action is actually complete.
6. Response Conventions
The current Yokefellow API surface is centered on JSON responses with an explicit ok field. The Quickstart already uses this pattern directly in its fetch example, checking both the HTTP status and the returned payload shape before treating the call as successful. The SDK client follows the same rule by throwing when the HTTP response is not successful or when the returned payload is not marked as successful.
A normal success response begins with:
{ "ok": true }
A normal error response begins with:
{ "ok": false, "error": { "code": "SOME_CODE", "message": "Readable message" }, "errorMessage": "Readable message" }
This explicit ok envelope matters because the current surface is not treating transport success and business success as the same thing. Builders should therefore evaluate both the HTTP response and the returned payload. That is already part of the current Quickstart and SDK guidance.
At the route level, success responses usually include three layers:
route success marker
route context
returned object data
For example, bucket-facing responses usually include the relevant bucket identifier and the object groupings attached to that bucket. A catalog response currently returns a composed surface rather than only one object. In the implemented route tree, the bucket catalog aggregates the core bucket record, posts, collections, classes, offerings, commerce data, snapshot data, state data, and an errors object for partial subroute failures. That makes the catalog route broader than a simple âbucket detailâ route and useful as a high-level integration anchor.
Funding preparation responses use a different success shape. In the current repo, deposit and transfer preparation responses return not only ok: true but also phase, action, chain context, contract addresses, onchain call information, whether finalization is required, a next-action descriptor, a status route, and invalidation hints. That is the response shape builders should expect from lifecycle-driven preparation routes.
In practice, the current surface uses a few recurring success patterns:
Basic object response
Used for simple reads such as app session, market reads, or object lookups.
{ "ok": true, "...": "object data" }
Grouped object response
Used when one route intentionally returns multiple related objects together, such as bucket catalog.
{ "ok": true, "bucketId": "<uuid>", "bucket": { }, "collections": [ ], "classes": [ ], "offerings": [ ] }
List response
Used for request history, queues, activity, and similar read families.
{ "ok": true, "bucketId": "<uuid>", "requests": [ ] }
Lifecycle preparation response
Used for funding and other tracked flows that are not complete at the first request.
{ "ok": true, "phase": "prepare", "action": "deposit", "chainId": 84532, "onchain": { }, "finalizeRequired": true, "nextAction": { }, "status": { } }
Lifecycle status response
Used for tracked transaction state.
{ "ok": true, "kind": "deposit", "txHash": "0x...", "chainStatus": "confirmed", "finalizationStatus": "pending" }
The important rule is that builders should preserve returned lifecycle metadata rather than throwing it away after the first request. The SDK Guide already emphasizes this at the client level, and the direct API surface follows the same logic. A prepare response is not just a one-time acknowledgment. It often contains the exact information needed for the next step of the flow.
7. Error Model
The current Yokefellow API surface uses a structured error model rather than ad hoc string responses. That fits the Developer Docs Hubâs requirement that the API Reference cover errors directly, and it aligns with the SDK Guideâs expectation that builders handle request failures, auth failures, and lifecycle failures explicitly instead of collapsing them into one generic empty state.
At the API level, the current error shape is:
{ "ok": false, "error": { "code": "VALIDATION_ERROR", "message": "Invalid request", "details": { } }, "errorMessage": "Invalid request" }
The errorMessage field exists as a transitional plain string for older clients, but builders should treat the structured error.code and error.message fields as the canonical interface.
The current implemented error families include:
BAD_REQUEST
VALIDATION_ERROR
UNAUTHORIZED
FORBIDDEN
NOT_FOUND
CONFLICT
WRONG_CHAIN
METHOD_NOT_ALLOWED
RATE_LIMITED
INTERNAL_ERROR
This matters because builders should not infer the meaning of a failure only from the HTTP code. The structured error code tells the app what kind of failure occurred, while the HTTP code tells the app how the failure was transported.
In practical terms, the current error model breaks into four important groups.
Validation failures
These occur before route logic fully runs. The current validation layer checks path params, query params, JSON bodies, UUIDs, wallet addresses, tx hashes, integer strings, and related shapes up front. When validation fails, the API returns a validation-style error rather than trying to continue with partially valid input.
Typical causes include:
malformed UUIDs
malformed wallet addresses
malformed tx hashes
invalid integer or amount fields
missing required body fields
invalid query combinations
Authentication and access failures
These occur when the integration is not recognized on a route that requires app auth or admin auth. The current auth layer accepts either a valid bearer token or a valid x-yf-app-key value for app access, while some routes also allow an admin session path. If neither is valid where required, the route returns an unauthorized error.
Typical causes include:
missing app key
bad app key
missing bearer token
invalid bearer token
accessing an app-scoped route as if it were public
This is consistent with the SDK Guideâs warning that builders should not confuse public reads with authenticated app-scoped reads.
Object and state failures
These occur when the route input is syntactically valid but the requested object or requested system state does not exist or cannot support the requested action.
Typical causes include:
bucket not found
offering not found
source or destination bucket not initialized onchain
request id not found
class or collection not found
unsupported state for the requested operation
These failures often return NOT_FOUND, BAD_REQUEST, or FORBIDDEN depending on whether the issue is object absence, invalid state, or ownership mismatch.
Lifecycle failures
These occur when a multi-step flow has not actually completed, has been continued incorrectly, or has failed onchain or in business finalization.
Typical causes include:
missing tx hash on status or finalization
wrong kind for status lookup
missing signature continuation fields on withdraw submit
trying to finalize the wrong business flow
reverted onchain transaction
incomplete business finalization after chain confirmation
This distinction matters because lifecycle incomplete is not the same thing as lifecycle failed. A transaction may be confirmed onchain while still being pending from Yokefellowâs business-finalization perspective. The current status surface is built to preserve that difference, and builders should keep it visible in the app instead of treating all non-complete states as one generic error.
The simplest error-handling rule is this: validate input early, surface auth failures distinctly, surface not-found and forbidden conditions honestly, and treat lifecycle state as part of the operation rather than as an afterthought.
8. Read APIs
The current implemented v1 route tree exposes a broader read surface than the first simplified SDK draft alone suggests. The most useful way to document it is by grouping routes by the primitive or question they answer. That keeps the API Reference aligned with the Hub and the SDK Guide while still reflecting the actual repo routes now present.
8.1 App session reads
Use these when the first question is whether the current integration is recognized correctly on an authenticated route.
GET /api/sdk/v1/apps/session
This is the cleanest first authenticated read because it proves the app key or bearer token is being accepted before the builder attempts state-changing actions. That is already the intended setup check in the SDK Guide.
8.2 Bucket primary reads
Use these when a bucket is the main participation surface the app is centered on.
GET /api/sdk/v1/buckets/:bucketId GET /api/sdk/v1/buckets/:bucketId/catalog GET /api/sdk/v1/buckets/:bucketId/funding GET /api/sdk/v1/buckets/:bucketId/snapshot GET /api/sdk/v1/buckets/:bucketId/state
In the current repo, catalog is the broadest bucket-centered read and usually the best first anchor because it composes several related bucket surfaces into one response. That matches the Quickstartâs recommendation to begin with a live bucket read.
funding is the more focused read when the integration cares about bucket funding state rather than the whole bucket participation surface. The SDK Guide already treats this as a separate builder question.
snapshot and state are additional implemented reads in the repo route tree and belong in the API Reference even though they are not yet the center of the current Quickstart narrative.
8.3 Bucket structure reads
Use these when the app needs the bucketâs output and participation structure rather than only the bucket record itself.
GET /api/sdk/v1/buckets/:bucketId/collections GET /api/sdk/v1/buckets/:bucketId/classes GET /api/sdk/v1/buckets/:bucketId/offerings GET /api/sdk/v1/buckets/:bucketId/permissions GET /api/sdk/v1/buckets/:bucketId/rewards
These are real implemented routes in the current repo tree. Some are more transitional in naming than others, but they belong in the direct route reference because builders working against the raw API need to know they exist.
collections and classes are useful when the integration needs to inspect output organization directly. offerings is the more direct offering-surface read. permissions exposes bucket permission state. rewards is currently part of the catalog composition path and should be documented as an implemented route even if broader wording elsewhere is moving toward offerings and rights language. That is a route-level documentation problem, not a reason to hide the route.
Transitional naming note
Some route names in the current v1 tree still reflect older terminology, especially /rewards. In practice, that route currently exposes bucket commerce and account-credit state rather than a standalone rewards concept. Builders should therefore treat some live route names as transport details and rely on the returned object shape to understand what the surface currently exposes.
8.4 Bucket operator and capability reads
Use these when the app is helping an operator inspect bucket-linked control surfaces.
GET /api/sdk/v1/buckets/:bucketId/capability-actions GET /api/sdk/v1/capabilities
These belong in the implemented route tree now and should be documented in the API Reference even though they are not part of the first simplified SDK walkthrough.
8.5 Wallet reads
Use these when the app is centered on one walletâs current state.
GET /api/sdk/v1/wallets/:wallet/entitlements GET /api/sdk/v1/wallets/:wallet/nfts
entitlements is the main wallet-facing rights/output read already described in the SDK Guide. It supports a wallet-centered app model and can be filtered by bucket and pending-state behavior.
nfts is also present in the current repo route tree and belongs in the direct API map.
8.6 Request and queue-state reads
Use these when the app needs to inspect unresolved participation paths, review work, or pending issuance.
GET /api/sdk/v1/buckets/:bucketId/offering-requests GET /api/sdk/v1/queues/requests GET /api/sdk/v1/queues/mint
These routes are important because Yokefellow does not flatten participation into only immediate success states. Request history, request queues, and mint queues are part of the visible system surface. That is already part of the SDK Guideâs read grouping and the vocabulary mapâs emphasis on queues and issuance inside technical docs.
The current implemented request-history route supports query filters including:
id
offeringId
wallet
status
limit
The current implemented mint-queue route supports:
bucketId
status
limit
The current implemented request-queue surface is also present and should be documented as part of the direct API even if the first SDK surface emphasizes the bucket-scoped request-history read more heavily.
8.7 Market reads
Use these when the app needs YES market state rather than bucket-specific state.
GET /api/sdk/v1/market/orderbook GET /api/sdk/v1/market/trades GET /api/sdk/v1/market/yes-price-stats
These routes are already part of the SDK Guideâs read surface and should remain one of the main route families in the API Reference. They answer different questions: visible orderbook state, recent trade flow, and YES pricing statistics.
8.8 Activity reads
Use these when the app needs recent visible system activity.
GET /api/sdk/v1/activity/recent GET /api/sdk/v1/activity/canonical
recent is the route surfaced by the current SDK client. canonical is also present in the implemented route tree and should be documented at the direct API level.
8.9 Object lookup reads
Use these when the app needs one concrete object rather than one bucket-centered or wallet-centered grouped surface.
GET /api/sdk/v1/classes/:classId GET /api/sdk/v1/classes/:classId/metadata GET /api/sdk/v1/collections/:collectionId GET /api/sdk/v1/mints/:mintId GET /api/sdk/v1/mints/:mintId/metadata
These routes are part of the current repo route tree and belong in the API Reference because they expose direct object lookups outside the broader bucket catalog surface.
8.10 Transaction lifecycle reads
Use these when the app needs tracked transaction state.
GET /api/sdk/v1/tx/status POST /api/sdk/v1/tx/status
The current status route supports lookup by transaction hash with optional lifecycle context such as:
txHash
chainId
kind
bucketId
fromBucketId
toBucketId
This is the main route for answering what Yokefellow currently thinks happened for a tracked funding or transfer action. That is already how the current Quickstart and SDK Guide position transaction status.
9. Write APIs
The current v1 write surface is grouped around five kinds of state change:
funding writes
offering participation writes
operator and configuration writes
queue and processing writes
transaction lifecycle completion
That grouping matches the way the current implementation actually behaves. Some writes create participant-side state. Some prepare or continue a chain-backed action. Some configure bucket-side participation surfaces. Some trigger work that is already queued.
9.1 Funding writes
These routes prepare or continue tracked funding actions.
POST /api/sdk/v1/funding/deposit POST /api/sdk/v1/funding/withdraw POST /api/sdk/v1/funding/transfer-between-buckets
Deposit
The current deposit route supports two body shapes.
Prepare:
{ "bucketId": "<uuid>", "wallet": "0x...", "amountYesRaw": "1000000000000000000" }
Capture-style continuation through the same route:
{ "bucketId": "<uuid>", "txHash": "0x..." }
In the implemented route, the prepare response returns a structured lifecycle payload, not just a success flag. That payload includes:
phase: "prepare"
action: "deposit"
bucketId
wallet
amountYesRaw
chainId
contracts.vaultAddress
contracts.yesAddress
onchain.approval
onchain.transaction
finalizeRequired
finalize
capture
nextAction
status
invalidationHints
That means the API Reference should present deposit as a preparation route that tells the builder what to do next, not as a one-step âdeposit completeâ endpoint.
Withdraw
The current withdraw route also supports two body shapes.
Prepare:
{ "bucketId": "<uuid>", "wallet": "0x...", "destinationWallet": "0x...", "amountYesRaw": "1000000000000000000" }
Submit with signature:
{ "bucketId": "<uuid>", "wallet": "0x...", "destinationWallet": "0x...", "amountYesRaw": "1000000000000000000", "issuedAt": "2026-04-08T15:00:00.000Z", "message": "Yokefellow withdraw available credit\n...", "signature": "0x..." }
This is an important place where the real route surface matters more than a generic narrative. Withdraw is not shaped like deposit. The prepare response returns a signature challenge payload with:
phase: "prepare"
action: "withdraw"
signature.required
signature.issuedAt
signature.message
signature.submitRoute
signature.submitBody
nextAction
status
The submit response then moves into phase: "submit" and returns tx-tracking information rather than a further finalize requirement. In the current implementation, finalizeRequired is false for withdraw.
Transfer between buckets
The current transfer route supports a prepare path and a capture-style continuation path.
Prepare:
{ "fromBucketId": "<uuid>", "toBucketId": "<uuid>", "ownerWallet": "0x...", "amountYesRaw": "1000000000000000000" }
Capture-style continuation:
{ "bucketId": "<uuid>", "txHash": "0x..." }
The implemented prepare response is lifecycle-shaped like deposit. It includes:
phase: "prepare"
action: "transfer_between_buckets"
fromBucketId
toBucketId
ownerWallet
amountYesRaw
chainId
contracts.settlementAddress
contracts.yesAddress
onchain.transaction
finalizeRequired
finalize
capture
nextAction
status
invalidationHints
This should be documented as a tracked funding flow, not as a simple transfer write.
9.2 Offering participation writes
These routes create or change participation state around offerings.
POST /api/sdk/v1/buckets/:bucketId/offering-requests PATCH /api/sdk/v1/buckets/:bucketId/offering-requests POST /api/sdk/v1/buckets/:bucketId/offerings/buy POST /api/sdk/v1/buckets/:bucketId/offerings/craft POST /api/sdk/v1/buckets/:bucketId/offering-events
Create offering request
Current create body:
{ "offeringId": "<uuid>", "wallet": "0x...", "qty": 1, "note": null, "selectedOutputId": null, "meta": {} }
This route creates request-based participation state. The implemented response is:
{ "ok": true, "bucketId": "<uuid>", "...created request payload..." }
The exact created payload is generated by the request-creation helper, so the API paper should describe it as returning the new request state rather than pretending the whole structure is static if the helper may evolve.
Update offering request
Current update body:
{ "id": "<request uuid>", "status": "approved", "note": null, "selectedOutputId": null, "meta": {} }
The current route only allows:
approved
fulfilled
rejected
This is important. The PATCH route is not a generic request-edit surface. It is a request-resolution surface.
Buy offering
Current body:
{ "offeringId": "<uuid>", "wallet": "0x...", "qty": 1, "note": null, "selectedOutputId": null, "meta": {} }
The current implementation is more constrained than a generic âbuy anythingâ route. It checks the offering and only allows this path when the offering is configured for:
mode = purchase
fulfillmentMode = auto_mint
If that is not true, the route returns an error that the offering is not configured for instant buy. The API Reference should document that constraint directly.
Craft offering
Current body:
{ "offeringId": "<uuid>", "wallet": "0x...", "note": null, "selectedOutputId": null, "meta": {} }
The current implementation only allows this when the offering has craft-style inputRules in its metadata. This route can also return a conflict-style response with needsApproval when the craft path requires approval.
That is worth documenting because it means craft is not just âbuy with a different name.â It has distinct validation and error behavior.
Submit offering event
Current body:
{ "wallet": "0x...", "appSlug": "snake-test", "eventType": "score_submitted", "metrics": {}, "meta": {} }
This route is part of the implemented v1 write surface even though it is not yet front-and-center in the current simplified SDK walkthrough. It records an app event, evaluates earned-mode offerings for the bucket, applies eligibility and claim-policy checks, creates offering requests where matched, and may auto-fulfill when the matched offering is configured for that path.
It belongs in the API Reference because it is a real programmatic write surface for event-driven offering resolution.
9.3 Operator and configuration writes
These routes create or change operator-controlled bucket state rather than only participant-side participation state.
POST /api/sdk/v1/buckets/:bucketId/offerings GET /api/sdk/v1/buckets/:bucketId/capability-actions POST /api/sdk/v1/buckets/:bucketId/capability-actions
Save bucket offering
Current save body includes fields such as:
title description imageUrl priceType priceYesRaw mode selectionMode fulfillmentMode status active sortOrder maxSupply maxPerWallet outputs meta
The current offerings write creates or updates a bucket offering and requires app or admin auth. It validates the output family directly: fixed offerings must have exactly one active output, while choice and random offerings must have at least one active output.
Capability actions
The capability-actions surface is both a read and a write surface. GET lists prior submissions for a bucket. POST creates a capability action submission with wallet, capabilityKey, optional scopeType and scopeRef, actionType, note, and payload. The route requires app or admin auth and checks that the wallet already holds the required bucket-relevant capability before the submission is accepted.
9.4 Queue and processing writes
The current v1 route tree includes a mint-queue execution write.
POST /api/sdk/v1/queues/mint
Current body:
{ "bucketId": "<uuid>", "limit": 10, "jobId": null, "retryFailed": false }
This is not a generic queue-edit endpoint. It triggers queue processing by calling the mint-job runner and returns the result of that run.
9.5 Transaction lifecycle completion write
The current explicit lifecycle completion route is:
POST /api/sdk/v1/tx/finalize
Current body:
{ "kind": "deposit", "txHash": "0x...", "chainId": 84532, "bucketId": "<uuid>", "fromBucketId": null, "toBucketId": null, "wallet": "0x...", "ownerWallet": null, "idempotencyKey": null }
The current implementation only supports:
deposit
transfer-between-buckets
It does not support withdraw finalization through this route. The doc should say that plainly.
10. Transaction Lifecycle Reference
The current lifecycle surface is not one generic âsubmit and waitâ pattern. The repo implements three distinct transaction-like flows:
deposit
withdraw
transfer-between-buckets
They share some concepts, but they do not have identical step shapes.
10.1 Deposit lifecycle
The deposit lifecycle begins with:
POST /api/sdk/v1/funding/deposit
using the prepare body.
The prepare response returns:
the chain to use
vault and YES token addresses
an approval call descriptor
a deposit transaction call descriptor
a finalize descriptor
a status descriptor
invalidation hints
The practical sequence is:
call POST /funding/deposit with bucketId, wallet, and amountYesRaw
perform the approval and deposit transaction on the wallet side
poll GET /api/sdk/v1/tx/status
call POST /api/sdk/v1/tx/finalize when the tx is confirmed
refresh the bucket and wallet surfaces named in invalidationHints
The current route also supports posting a txHash back to /funding/deposit, but the implemented code forwards that into the finalize handler. The canonical documentation path should still emphasize /tx/finalize as the explicit lifecycle completion route.
10.2 Withdraw lifecycle
The withdraw lifecycle begins with:
POST /api/sdk/v1/funding/withdraw
using the prepare body.
The prepare response returns a signature payload, not an onchain call descriptor. That is the core distinction from deposit.
The practical sequence is:
call POST /funding/withdraw with bucketId, wallet, optional destinationWallet, and amountYesRaw
receive issuedAt, message, and signature.submitBody
sign the returned message with the wallet
call POST /funding/withdraw again with the signature fields included
poll GET /api/sdk/v1/tx/status
In the current implementation, withdraw does not use /tx/finalize. The route returns finalizeRequired: false.
That difference should be explicit in the API paper. It is one of the places where âtransaction lifecycleâ and âexplicit finalizationâ are not the same thing.
10.3 Transfer-between-buckets lifecycle
The transfer lifecycle begins with:
POST /api/sdk/v1/funding/transfer-between-buckets
using the prepare body.
The response returns:
chain context
settlement and YES token addresses
onchain transaction call data
finalize descriptor
status descriptor
invalidation hints
The practical sequence is:
call POST /funding/transfer-between-buckets
submit the onchain transfer transaction
poll GET /api/sdk/v1/tx/status
call POST /api/sdk/v1/tx/finalize
refresh the affected bucket and wallet surfaces from invalidationHints
10.4 Status lookup
The current status route supports both GET and POST:
GET /api/sdk/v1/tx/status POST /api/sdk/v1/tx/status
Supported input fields are:
txHash
chainId
kind
bucketId
fromBucketId
toBucketId
The current status payload includes:
ok
kind
chainId
txHash
chainStatus
finalizationStatus
confirmations
explorerUrl
resultSummary
result
error
The implementation currently uses these chain statuses:
not_found
pending
confirmed
reverted
and these finalization statuses:
not_started
pending
completed
failed
not_required
That means the API paper should teach builders to distinguish chain state from business finalization state. A tx can be confirmed while business finalization is still pending.
10.5 Finalization
The current finalize route is:
POST /api/sdk/v1/tx/finalize
Supported kind values are:
deposit
transfer-between-buckets
The route does four main things:
resolves the chain id
checks current onchain status
checks whether business finalization already happened
runs deposit-capture finalization if still needed
Its response is status-shaped rather than just action-acknowledgment shaped. The returned payload includes:
kind
chainId
txHash
chainStatus
finalizationStatus
confirmations
resultSummary
result
status
capture
refreshHints
idempotencyKey
alreadyFinalized when applicable
That makes /tx/finalize both a completion endpoint and a structured finalization-status endpoint.
10.6 Practical lifecycle rule
The safest rule for builders is:
prepare through the funding route
do the wallet-side or chain-side step
poll tx/status
finalize only where the returned flow requires it
refresh the bucket and wallet surfaces the API tells you to refresh
That rule matches the implemented route behavior better than a generic âevery tx must be finalizedâ statement.
11. Object Groupings
The current v1 surface returns several grouped response shapes that matter more than the raw endpoint list. Builders do not only need routes. They need to know which routes return one object, which return a composed surface, and which return queue or lifecycle state.
11.1 App session object
Returned by:
GET /api/sdk/v1/apps/session
Current shape:
{ "ok": true, "auth": { "kind": "app", "scheme": "app-key", "appKeyId": "<id or null>" } }
This is the current authenticated integration-recognition object.
11.2 Bucket catalog object
Returned by:
GET /api/sdk/v1/buckets/:bucketId/catalog
This is one of the most important grouped objects in the current surface. The implemented route composes several subroutes together and returns a multi-surface bucket response.
The route returns fields including:
ok
bucketId
wallet
round
bucket
posts
collections
registryAddress
classes
offerings
commerce
snapshot
state
hasErrors
errors
This should be documented as a composed integration anchor, not as a single-table bucket record.
11.3 Bucket funding object
Returned by:
GET /api/sdk/v1/buckets/:bucketId/funding
This is another grouped object. The implemented route composes snapshot, the transitional /rewards commerce surface, and bucket state into one funding-oriented response.
The route returns fields including:
ok
bucketId
wallet
round
snapshot
accountCredit
walletState
capabilities
state
hasErrors
errors
Even where the underlying route naming is transitional, the API paper should reflect the actual current response surface.
11.4 Wallet entitlements object
Returned by:
GET /api/sdk/v1/wallets/:wallet/entitlements
This is a composed wallet-facing object, not just a single entitlements table dump. The implemented route combines wallet NFTs, capabilities, bucket permissions, and optional bucket-commerce context.
The response includes fields such as:
ok
wallet
bucketId
includePending
limit
walletState
walletState.ownedMints
walletState.queuedMintJobs
walletState.pendingRequests
walletState.indexedHoldings
walletState.counts
walletState.ownedClassIds
walletState.ownedCollectionIds
capabilities
permissions
accountCredit
hasErrors
errors
That is why this route is the right wallet-facing integration surface in the docs, rather than pretending rights-related state comes from one flat universal object.
11.5 Offering request object
Returned by:
GET /api/sdk/v1/buckets/:bucketId/offering-requests GET /api/sdk/v1/queues/requests POST /api/sdk/v1/buckets/:bucketId/offering-requests PATCH /api/sdk/v1/buckets/:bucketId/offering-requests
The implemented request rows are rich objects, not only request ids and statuses. The current mapped request shape includes fields such as:
id
bucketId
offeringId
offeringTitle
selectedOutputId
classId
className
collectionId
collectionName
wallet
qty
status
selectionMode
mode
fulfillmentMode
requestSource
requestPayload
requestNote
paymentSourceBucketId
paymentStatus
reservedAmountYesRaw
capturedAmountYesRaw
releasedAmountYesRaw
resolutionType
resolutionPayload
resolutionNote
reviewedBy
reviewedAt
fulfilledBy
fulfilledAt
meta
createdAt
updatedAt
mint
mint.id
mint.status
mint.quantity
mint.tokenId
mint.txHash
mint.createdAt
That should be one of the core object groupings in the API paper.
11.6 Mint queue job object
Returned by:
GET /api/sdk/v1/queues/mint
Current queue jobs include:
id
mintId
bucketId
classId
status
attempts
lastError
txHash
startedAt
completedAt
meta
createdAt
updatedAt
wallet
quantity
tokenId
mintStatus
className
collectionName
collectionAddress
standard
That is a queue inspection object, not just a generic job runner return shape.
11.7 Funding preparation object
Returned by:
POST /api/sdk/v1/funding/deposit POST /api/sdk/v1/funding/withdraw POST /api/sdk/v1/funding/transfer-between-buckets
These are grouped lifecycle objects. They should be documented as preparation descriptors, not simple success payloads.
Across the current implementation, these objects may contain:
phase
action
identifiers like bucketId, fromBucketId, toBucketId, wallet, ownerWallet
amountYesRaw
chainId
contracts
onchain
signature
finalizeRequired
finalize
capture
nextAction
status
invalidationHints
11.8 Transaction status object
Returned by:
GET /api/sdk/v1/tx/status POST /api/sdk/v1/tx/status POST /api/sdk/v1/tx/finalize
This is a lifecycle-state object with fields including:
ok
kind
chainId
txHash
chainStatus
finalizationStatus
confirmations
explorerUrl
resultSummary
result
error
The finalize route extends that shape with operational fields like:
status
capture
refreshHints
idempotencyKey
alreadyFinalized
11.9 Market and activity objects
The current route tree also includes direct grouped objects for:
GET /api/sdk/v1/market/orderbook GET /api/sdk/v1/market/trades GET /api/sdk/v1/market/yes-price-stats GET /api/sdk/v1/activity/recent GET /api/sdk/v1/activity/canonical
These are largely pass-through route exports to the broader app-level market and activity surfaces, so the API paper should document them as stable route families while avoiding overpromising a static internal schema unless those underlying route payloads are being documented separately in the same doc set.
11.10 Practical grouping rule
The simplest way to read the current API surface is:
use bucket catalog when you need one broad bucket-centered participation object
use bucket funding when you need the bucketâs funding-oriented composed state
use wallet entitlements when you need wallet-facing holdings and pending state
use offering request objects when you need participation lifecycle state
use mint queue jobs when you need unresolved issuance work
use funding preparation objects when you need the next lifecycle step
use tx status objects when you need the current truth of a tracked action
That keeps the API paper grounded in the real grouped surfaces the repo exposes today.
12. Production Notes
The current Yokefellow API surface should be integrated as a lifecycle-driven system, not as a collection of unrelated endpoints. A builder should not treat a successful write as the same thing as a completed business result. In the current surface, deposit, withdraw, and transfer-between-buckets all return structured next-step information, and some of those flows require later status checks or explicit finalization before the integration should present them as complete. That is already part of the current Quickstart and SDK guidance, and the direct API surface should be read the same way.
The safest implementation pattern is to separate four concerns clearly in code: request authentication, wallet context, chain-side execution, and Yokefellow-side lifecycle state. App auth proves the integration is recognized. Wallet context tells the API which user-side state the route is about. The wallet or chain layer still handles signing or transaction submission where required. The API then reports what Yokefellow thinks happened through status and finalization routes. Keeping those layers separate makes failures easier to reason about and keeps the app from claiming completion too early.
Builders should preserve lifecycle metadata from responses instead of discarding it after the first call. The current funding routes return next-action information, status-route context, and invalidation hints because the platform expects the integration to continue the flow deliberately. The same is true for signature-based withdraw continuation and explicit finalization where required. A production integration should store the identifiers and lifecycle fields needed to resume the flow cleanly after refresh, retry, or UI transition rather than assuming the user will stay on one screen until the action is over.
A production app should also confirm returned state through the surface that actually matters to the feature it is building. For bucket-centered views, that usually means refreshing the bucket catalog or funding surface. For wallet-centered views, that usually means refreshing entitlements, wallet NFT state, request history, or queue state as appropriate. For transaction flows, that means reading transaction status and only treating the action as resolved when the returned lifecycle state says it is resolved. Quickstart already frames this as the difference between âthe call returnedâ and âthe lifecycle result is confirmed,â and that should remain the production rule.
Error handling should stay specific. A good production integration should distinguish validation failures, auth failures, not-found conditions, lifecycle-incomplete states, and true operation failures instead of flattening them into one generic error banner or one empty state. The SDK Guide already emphasizes that reads, writes, and lifecycle helpers can all fail differently, and the API surface follows that same expectation. A user should be able to tell whether the request was malformed, whether access failed, whether the object does not exist, whether the chain transaction is still pending, or whether the business finalization step has not completed yet.
Builders should also design around route groupings rather than one-off endpoint calls. The current surface is strongest when used through its real object families: bucket catalog for broad bucket-centered state, bucket funding for funding-oriented state, wallet entitlements for wallet-facing holdings and pending state, offering request objects for participation lifecycle state, mint and request queues for unresolved work, and transaction status for tracked funding actions. That approach keeps the integration close to Yokefellowâs actual primitives instead of rebuilding product logic from scattered route calls.
Finally, this reference should hand off cleanly to the next document in the Hub. Once a builder understands the base route, auth model, request and response conventions, read families, write families, lifecycle routes, and grouped objects, the next problem is usually no longer route lookup. It is product structure. That is where the Integration Playbook takes over. The API Reference explains how to call the surface. The Integration Playbook should explain how to assemble those calls into a real bucket-centered app, offering flow, operator surface, or partner integration without losing the platformâs lifecycle and object model.