Recipes and Examples

Most outcomes on XKOVA are a short, ordered sequence of operations where one step's output feeds the next. These recipes walk the common flows end to end and identify which steps belong to the customer backend, a purpose-bound hosted experience, or a private institution-staff workflow.

How to read these

Every recipe is workflow shaped. A single write rarely finishes the job: a payment still needs a member signature, a treasury transfer still needs a signer quorum, and settlement is observed on chain rather than returned inline. The off chain steps (a member's EIP-712 signature in their own wallet, relayer submission and on chain settlement) are noted where they occur, and terminal status is reached by polling the relevant read. For why the API is shaped this way, see the Non-custodial Model.

Customer-server API steps use the sandbox base URL https://sandbox-api.xkova.com/v1 and a tenant key $XKOVA_API_KEY that you keep server side. Purpose-bound member ceremonies and private institution-staff workflows are identified separately and are not called with that tenant key.

Accept your first payment

1. Preview feasibility and fees (optional; create re-prices): POST /v1/payments/quote.
2. Create it: POST /v1/payments. The response carries the resource and its pending_sign status.
3. From your BFF, start an exact member action with beginMemberAction. Hosted members complete a fresh passkey ceremony in the branded Account Center. FI/BYO OIDC members complete the fresh assurance profile registered for that application.
4. Complete the action through the BFF helper. It exchanges the one-use result and opens the controlled signing surface without putting a provider token, XKOVA member credential, or signing authority in browser JavaScript.
5. After the hosted ceremony completes, continue polling the customer-server payment resource.
6. Poll GET /v1/payments/{id} until status: confirmed.

Send to someone without an account (escrow plus claim)

1. Create the held payment: POST /v1/escrows. A claim token is issued.
2. The sender completes the same purpose-bound hosted signing ceremony as above.
3. The recipient opens the claim link and completes its hosted verification and resolution ceremony.

The claim path uses a capability token, not an API key, so the recipient never needs credentials. See Escrow and Claims.

Stand up a treasury vault and move funds

1. An institution administrator creates the Safe, signers, and threshold through Core Rails.
2. An authorized institution staff member drafts the transfer in its contextual Core Rails session.
3. Each signer completes the institution-staff signing ceremony until the Safe quorum is met.
4. Core Rails executes the approved transfer and presents its settlement status.

The request creator cannot self approve when the clause is satisfiable without them. See Treasury and Policies and Quorum Governance.

Issue and distribute a real-world asset token

1. Deploy: POST /v1/tokenization/erc1155, then poll GET /v1/tokenization/tokens/{id} until status: active.
2. Bind metadata: publish an asset schema, POST /v1/rwa/tokens/{id}/schema-binding, then commit fields with POST .../fields/{fieldPath}.
3. Mint to holders, then create and execute a distribution: POST /v1/rwa/tokens/{id}/distributions then POST .../{distId}/execute, then poll until the distribution reads completed.

The batched payout leaves the treasury Safe as one quorum approved transfer; sanctioned holders are excluded server side. See Real-World Assets and Cap Tables and Distributions.

Receive events reliably

1. Subscribe to the event types you care about: POST /v1/webhook-endpoints.
2. On each delivery, verify XKOVA-Webhook-Signature plus its Ed25519 companion over the raw body, then handle idempotently by the event id (XKOVA-Webhook-Event-Id, equal to the envelope id); reserve the delivery id (XKOVA-Webhook-Delivery-Id) for delivery-level tracing.
3. Rotate the secret with POST .../{id}/rotate. A grace window keeps the old secret valid during the cutover.

The SDK ships verifyWebhookSignature for step two. See Webhooks.

Set up your workspace

Setup is console-first, then API. In the console: sign up, follow the emailed Login Link, pick a direction on the intent screen, then work the checklist: commit a fee schedule and create an API key (held for owner approval on a fresh workspace; attest under Governance, Approvals, then re-submit). From your backend: poll GET /v1/onboarding/status until setup reads complete, read the automatic chain and asset catalogs, provision account holders, and make the first payment with a rails-eligible, certified asset. The intent choice does not pin a network. See Operator Onboarding for the console path and the Quickstart for the first call.

Related

For the exact request and response shapes of customer-server operations referenced here, see the interactive reference or the operations list. For supported composed customer-server helpers, see SDK Workflows.