XKOVA Docs
Docs / API Reference / Recipes and Examples

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. Each maps to a workflow you can also run as one SDK call.

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.

All examples use the sandbox base URL https://sandbox-api.xkova.com/v1 and a tenant key xkv_test_... that you keep server side.

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 id, status, and a signing_url.
  3. Hand the member the signing_url, or drive the signing yourself with the ?token= it carries: GET .../signing-session then GET .../member-jwt.
  4. The member signs the TransferIntent plus Permit in their wallet; submit the signatures to POST .../signatures.
  5. Poll GET /v1/payments/{id} until status: confirmed.
With the SDK this is one call: client.workflows.directPaymentSend({ payment, sign }). See SDK Workflows.

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 signs (same signing session pattern as above) and you submit the signature.
  3. The recipient opens the claim link: GET /v1/claims/{token} then POST .../send-otp then POST .../verify-otp then POST .../resolve.

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. Create the Safe and add signers plus a threshold: POST /v1/treasury/wallets.
  2. Draft a transfer: POST /v1/treasury/wallets/{walletId}/transfers.
  3. Each signer signs the Safe hash; POST /v1/treasury/transfers/{id}/signatures until quorum.
  4. Execute, then poll until confirmed: POST .../execute then GET .../{id} until state: confirmed.

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 (this pins the sandbox network), then work the checklist: enable a token, 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, provision account holders, and make the first payment. See Operator Onboarding for the console path and the Quickstart for the first call.

Related

For the exact request and response shapes of every operation referenced here, see the interactive reference or the operations list. For these same flows as single SDK calls, see SDK Workflows.