SDK execution client

The SDK drives the full journey: quote, plan, execute from the user's own wallet, track to a terminal state. It is published on npm as @synfin/client (MIT). Status, honestly: v0, the API surface may evolve with design-partner feedback before a 1.0, so pin an exact version.

Install

npm install @synfin/client

Node 18+ or any modern browser. Zero runtime dependencies. Get a free API key at portal.synfin.xyz.

Minimal example

import { createClient } from '@synfin/client';

const synfin = createClient({ apiKey: process.env.SYNFIN_API_KEY });

// 1. quote (keyed, so it carries your clientFees), ranked best net first
const quote = await synfin.getQuote({
  from: 'CC', to: 'USDCx', amount: '100',
  feeBps: 30, feeRecipient: 'yourparty::1220...', // your integrator fee
});
const best = quote.venues.find((v) => v.available);

// 2. plan: the server pins the numbers and the memo floor
const plan = await synfin.createPlan({
  from: 'CC', to: 'USDCx', amount: '100',
  venueId: best.venueId,
  takerParty: 'yourparty::1220...',
  idempotencyKey: crypto.randomUUID(),
});

getQuote and createPlan call the hosted API with your key; executePlan and track below are wallet-driven and need no key.

The journey

// 1. quote (GET /api/quote with your fee) and let the user pick
// 2. plan (POST /api/execute/plan) pins the numbers server-side
// 3. execute: YOUR wallet performs the steps
const handle = await executePlan(plan, {
  wallet,                       // your WalletAdapter
  hooks: {
    onStatus: (s) => render(s), // INITIATED, COMPLETED, ...
    onStep: (step, result) => log(step.kind, result),
  },
});

// 4. track: observe the user's own ledger view until terminal
let state = await track(handle, { wallet, hooks });
while (!isPartnerTerminal(state.status)) {
  await sleep(15_000);
  state = await track(handle, { wallet, hooks });
}

From @synfin/client: import { executePlan, track, isPartnerTerminal } from '@synfin/client'.

• executePlan refuses an expired plan, performs the venue-deposit step (and the fee-escrow-lock step when the plan collects fees), and emits INITIATED.
• track reads the deposit offer's state and the payout through your wallet adapter and derives the lifecycle state. On COMPLETED it releases the fee escrow; on SLIPPAGE_FAILED it does not.
• The hooks mirror the pattern wallet developers know from LI.FI's executeRoute: the SDK provides steps and status, your code signs and renders. The SDK never holds keys.

The wallet adapter

You implement one interface against your participant view; the SDK does the rest.

<script src="https://unpkg.com/@synfin/widget@0.1.0"></script>
<synfin-widget
  api-key="sk_live_..." fee-bps="30" fee-recipient="you::1220..."
  from="CC" to="USDCx" amount="100"></synfin-widget>

npm install @synfin/widget

import '@synfin/widget'; // registers <synfin-widget>
// React: import { SynfinWidget } from '@synfin/widget/react';