Arkade Assets

Code for the arkade:<asset> → arkade:<asset> route — BTC against an Arkade Asset such as USDT. The SDK and wire format use offer in identifiers such as createOffer; that is the code name for the funded swap. Model: Markets and Execution · reference: Arkade Asset Swaps.

pnpm add @arkade-os/sdk @arkade-os/swap @arkade-os/solver-discovery @scure/base

Prerequisites:

an initialized Arkade IWallet — Create Your Wallet;
a registry URL and the Arkade server URL.

Discover and Price

A card advises the pricing formula — the spot feed and the fee — and only a fill commits the solver to your swap. The quote below is calculated from those at runtime rather than received. No inventory is reserved, so application policy decides which registries and markets are acceptable.

import {
  IndexedDbAssetSwapRepository,
  QUOTE_OPTIONS,
  discoverMarkets,
  findMarket,
  makeCachedFeedFetch,
  validatePlan,
} from "@arkade-os/swap";
import { quoteOffer } from "@arkade-os/solver-discovery";

const swapRepository = new IndexedDbAssetSwapRepository(); // browser; use InMemoryAssetSwapRepository in Node
const quoteFetch = makeCachedFeedFetch();

const markets = await discoverMarkets({
  network,
  registryUrl: solverRegistryUrl,
  repository: swapRepository,
});

const selected = findMarket(markets, fromAssetId, toAssetId);
if (!selected?.market) throw new Error("No market for this pair");

const plan = await quoteOffer(selected.market, {
  give: selected.give,
  giveAmount: "0.001",
  ...QUOTE_OPTIONS,
  fetchImpl: quoteFetch,
});

const planError = validatePlan(plan, giveBalance, dustAmount);
if (planError) throw new Error(`Swap cannot be funded: ${planError}`);

Mind the units. giveAmount is a display amount when passed as a string or number, converted by the asset’s decimals — only bigint is atomic. Passing 100000 meaning sats quotes 100,000 BTC. validatePlan’s two operands are the opposite: both bigint, so wrap the wallet’s settled balance with BigInt(...). Show the deposit, receive amount, and fee before funding.

Fund

createOffer registers the covenant and returns the type 0x03 extension; it broadcasts nothing. Registration marks the contract genericallySpendable: false, which is what stops send, settle or background renewal from forfeiting a live offer behind your back. The swap goes live when wallet.send funds the address and includes the extension — that packet is what makes the funded swap discoverable to solvers watching the transaction stream. Omit it and the deposit sits there, indexed by nobody.

import { asset, type IWallet } from "@arkade-os/sdk";
import { BTC_ASSET_ID, addAssetSwap, createOffer, type AssetSwap } from "@arkade-os/swap";
import { hex } from "@scure/base";
import type { OfferPlan } from "@arkade-os/solver-discovery";

async function fundAssetSwap(wallet: IWallet, plan: OfferPlan): Promise<AssetSwap> {
  const depositIsBtc = plan.deposit.asset.id === BTC_ASSET_ID;
  const receiveIsBtc = plan.receive.asset.id === BTC_ASSET_ID;

  const offer = await createOffer(wallet, arkadeServerUrl, {
    wantAmount: plan.receive.atomic,
    ...(receiveIsBtc
      ? { offerAsset: asset.AssetId.fromString(plan.deposit.asset.id) }
      : { wantAsset: asset.AssetId.fromString(plan.receive.asset.id) }),
  });

  const fundingTxid = await wallet.send({
    address: offer.address,
    amount: depositIsBtc ? Number(plan.deposit.atomic) : undefined,
    assets: depositIsBtc
      ? undefined
      : [{ assetId: plan.deposit.asset.id, amount: plan.deposit.atomic }],
    extensions: [offer.extension],
  });

  const swap: AssetSwap = {
    id: fundingTxid,
    fromAsset: plan.deposit.asset.id,
    toAsset: plan.receive.asset.id,
    fromAmount: plan.deposit.atomic.toString(),
    toAmount: plan.receive.atomic.toString(),
    swapAddress: offer.address,
    swapPkScript: hex.encode(offer.swapPkScript),
    offerHex: offer.offerHex,
    fundingTxid,
    status: "pending", // see Asset Swap States in the lifecycle reference
    createdAt: Date.now(),
  };

  await addAssetSwap(swapRepository, swap);
  return swap;
}

Identical terms derive the same address, which is why the record carries both offerHex and fundingTxid — the txid is what identifies this deposit.

Track and Cancel

watchOfferSwaps subscribes to the wallet’s contract events and drives each swap’s status for you, persisting before it notifies:

import { watchOfferSwaps } from "@arkade-os/swap";

const watcher = await watchOfferSwaps({
  wallet,
  arkServerUrl: arkadeServerUrl,
  repository: swapRepository,
  onUpdate: (swap) => render(swap),
});

Only a registered covenant produces events, which createOffer handles. In Node you need an EventSource implementation for live updates to arrive. restoreAssetSwaps is the fallback, rebuilding records by scanning sent transactions for offer packets. An unfilled swap has no expiry — it stays open until filled or cancelled:

import { cancelOffer } from "@arkade-os/swap";

const cancelTxid = await cancelOffer(wallet, arkadeServerUrl, swap.offerHex, {
  repository: swapRepository,
  fundingTxid: swap.fundingTxid, // selects this deposit when offers share an address
  swapAddress: swap.swapAddress, // pins the server key the covenant was built with
});

cancelOffer writes the cancelling → cancelled transition itself, so do not write it yourself. Cancellation races a fill. If the deposit is already spent the call throws — that means the swap completed. Reconcile the spending transaction before reporting an error to the user.

Lightning

Pay and receive Lightning from an Arkade balance.

Arkade Asset Swaps

Review pricing, funding, lifecycle, and cancellation.

Understand Intents

Build with Intents

Earn Fees

Reference

Discover and Price

Fund

Track and Cancel

Lightning

Arkade Asset Swaps

​Discover and Price

​Fund

​Track and Cancel

Lightning

Arkade Asset Swaps

Discover and Price

Fund

Track and Cancel