Build a 0Gate swap flow

Use 0Gate for public swap journeys when the customer can complete the hosted 0Bit experience. The source repos show swap as a hosted iframe/kit-block flow; partner-level headless swap quote and execute APIs are not the public default.

Flow boundary

Implementation shape

1. Create a swap intent before opening 0Gate.
2. Lock the server-created session to swap.
3. Mount the swap kit block or the hosted widget with a session-bound flow.
4. Store the 0Gate session id, your swap intent id, and every webhook event id.
5. Reconcile from trusted server state if the callback fires before webhook delivery.

async function startSwap(input: SwapIntent) {
  const intent = await swapIntents.create({
    accountId: input.accountId,
    fromAsset: input.fromAsset,
    toAsset: input.toAsset,
    amountIntent: input.amountIntent,
    status: 'pending_session',
  });

  const session = await gateSessions.createForAttempt({
    attemptId: intent.id,
    flow: 'swap',
    userReference: intent.id,
    idempotencyKey: `swap:${intent.id}`,
  });

  await swapIntents.attachGateSession(intent.id, session.id);
  return { intentId: intent.id, clientSecret: session.clientSecret };
}

Swap state model

Quote expectations

Swap pricing is sensitive because it touches liquidity and execution correctness. Keep this public guide to user-flow behavior; exact quote surfaces, fields, and execution semantics belong in approved API reference pages.

Webhook handling

async function applySwapEvent(event: GateSessionEvent) {
  const intent = await swapIntents.findByGateSession(event.data.id);
  if (!intent) return;

  const firstSeen = await webhookEvents.insertOnce(event.id);
  if (!firstSeen) return;

  if (event.type === 'gate_session.completed') {
    await swapIntents.fulfillOnce(intent.id, { sourceEventId: event.id });
  }

  if (['gate_session.failed', 'gate_session.expired', 'gate_session.cancelled'].includes(event.type)) {
    await swapIntents.closeWithoutFulfillment(intent.id, event.type);
  }
}

Production checklist

• Keep public swap UX on hosted 0Gate unless a different product entitlement is approved.
• Keep provider, treasury, and routing internals out of public-facing swap UX.
• Treat preview pricing as indicative unless the API reference says it is locked.
• Make browser success a processing state only.
• Fulfill from signed backend state and dedupe duplicate events.

Related pages