Skip to content

Developers: dex-sdk quickstart

dex-sdk is Kadia’s TypeScript client for the DEX service. It keeps the dangerous part of a trade on your side: the service builds the transaction, and dex-sdk checks it before your user’s wallet is asked to sign.

  1. Connect the person’s browser wallet (EIP-12). It signs; it never submits.
  2. Quote. Ask the service for a price. Every answer carries the chain context, and every request sends it back, so a quote, a build and a submit all refer to the same chain state.
  3. Build and review. Find the funding boxes, which the wallet, the service and (optionally) your own node must all report, and ask for the unsigned transaction. client.build() runs verifyBuild on it: it decodes the transaction, checks it against your request and the quote (market, minimum payout, owner, payout and change scripts, inputs), checks ERG and tokens are conserved, and throws if anything differs. built.review holds the decoded figures to show before signing.
  4. Sign and submit. signWithWallet asks the service to authorise the request, has the wallet sign exactly that transaction, and has the service validate the signed bytes. client.submit() refuses a signed transaction whose inputs or outputs differ from the build.
import { connectWallet, DexClient, discoverFunding, discoverWallets, fundingNeeded, signWithWallet } from "@kadia/dex-sdk";
// 1. Connect the person's browser wallet (EIP-12, such as Nautilus). It only ever signs; it never submits.
export async function connect(injected) {
const [choice] = discoverWallets(injected);
return connectWallet(choice);
}
// 2. Quote. Every answer from the service carries the chain context; send it back with each request.
export async function quoteSwap(client, marketId, amount) {
const { context } = await client.markets();
const { data: quote } = await client.quote({
context, marketId, side: 0, amount, slippageBps: 50, expiryHeight: context.upcomingHeight + 720,
});
return { context, quote };
}
// 3. Build and review. build() runs verifyBuild on the service's unsigned transaction and throws
// if it differs from what you asked for; built.review holds the decoded figures to show the person.
export async function buildSwap(client, wallet, context, quote) {
const probe = await discoverFunding({ wallet, client, context });
const ownerScript = "0008cd" + probe.publicKey;
const needed = fundingNeeded(quote, { payoutScript: ownerScript });
const funding = await discoverFunding({ wallet, client, context, needed });
return client.build({
context, operation: "create", marketId: quote.marketId, quoteId: quote.id, ownerPublicKey: funding.publicKey,
payoutScript: ownerScript, changeScript: ownerScript, fundingBoxes: funding.selected,
});
}
// 4. Sign and submit. signWithWallet signs exactly the reviewed transaction; submit() refuses a
// signed transaction whose inputs or outputs differ from the build.
export async function signAndSubmit(client, wallet, built) {
const signed = await signWithWallet(wallet, built.data, client.nativeSigningAuthorizer());
const { data } = await client.submit(built.data, signed);
return data; // { transactionId, status: "pending", wireSha256 }
}
// Putting it together, against Kadia's DEX service through the site's own proxy.
export async function placeSwap(injected, marketId, amount, client = new DexClient("/api/dex/testnet/v1")) {
const wallet = await connect(injected);
const { context, quote } = await quoteSwap(client, marketId, amount);
const built = await buildSwap(client, wallet, context, quote);
return signAndSubmit(client, wallet, built);
}
  • The base URL. Through a Kadia site, the service is at /api/dex/testnet/v1 on the same origin. See the DEX service API.
  • Show the review. Put built.review’s figures in front of the person before signAndSubmit, and let them stop there.
  • Funding. discoverFunding builds from boxes every source reports, and says so in note when it left some out. Pass onDifference: "refuse" to stop instead, and nodes to add your own node as a third source.
  • A build you got elsewhere. verifyBuild(intent, signing, quote) is exported too. Run it yourself on any build before it reaches a wallet.
  • Other order types (limit, stop, DCA, grid, route) use the same steps, with their own quote calls and an orderKind on the build.
Technical details

Source: kadia-dex packages/dex-sdk at commit 7ce1595 (7ce159587dc8c0bd78d6a5fbe0f7f8e7dde3920e), as vendored in kadia-web’s packages/dex-sdk. This page’s code is kadia-web’s apps/docs/examples/dex-sdk-quickstart.mjs. A test runs it end to end against that SDK, a mock EIP-12 wallet and a scripted service, and fails if this page and the file differ.