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.
The flow
Section titled “The flow”- Connect the person’s browser wallet (EIP-12). It signs; it never submits.
- 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.
- 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()runsverifyBuildon 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.reviewholds the decoded figures to show before signing. - Sign and submit.
signWithWalletasks 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.
The code
Section titled “The code”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/v1on the same origin. See the DEX service API. - Show the review. Put
built.review’s figures in front of the person beforesignAndSubmit, and let them stop there. - Funding.
discoverFundingbuilds from boxes every source reports, and says so innotewhen it left some out. PassonDifference: "refuse"to stop instead, andnodesto 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
orderKindon 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.