Quickstart

Swap on a Flashnet pool in one signed intent

This walks you from a fresh install to a successful USDB swap. You need a Spark wallet mnemonic and the URL of a Flashnet Execution gateway.

Install

The SDK is pre-release. Until the mainnet npm publish, install it from a git tag.

Add this to your package.json:

{
  "dependencies": {
    "@flashnet/sdk": "github:flashnetxyz/ts-sdk#v0.0.0-alpha1",
    "@buildonspark/spark-sdk": "latest"
  }
}

Then:

npm install --ignore-scripts

--ignore-scripts matters. @flashnet/sdk’s prepare hook runs rollup -c against its devDependencies before your installer has linked them, so a plain npm install may fail with Cannot find module 'rollup'. The --ignore-scripts flag avoids that ordering. npm still builds the package on its own pass, so you end up with a working dist/.

If you prefer bun and the dist isn’t there after install, build it manually:

cd node_modules/@flashnet/sdk && bunx tsc --noEmit && bunx rollup -c

Verify by importing one of the clients:

import { ExecutionClient, TradingClient } from "@flashnet/sdk";

Create the clients

import { SparkWallet } from "@buildonspark/spark-sdk";
import { ExecutionClient, TradingClient } from "@flashnet/sdk";

const sparkWallet = await SparkWallet.initialize({
  mnemonicOrSeed: process.env.MNEMONIC,
  options: { network: "REGTEST" },
});

const execClient = new ExecutionClient(sparkWallet, {
  gatewayUrl: process.env.GATEWAY_URL,
  rpcUrl: process.env.RPC_URL,
  chainId: Number(process.env.CHAIN_ID),
});

await execClient.authenticate();

const trading = new TradingClient(execClient, {
  conductorAddress: process.env.CONDUCTOR_ADDRESS,
});

authenticate() derives the Execution-side EVM address from the same identity key that controls the Spark wallet. There is no separate signup, faucet, or funding step.

Swap BTC for USDB

const result = await trading.swap({
  assetInAddress: "btc",
  assetOutAddress: process.env.USDB_ADDRESS,
  amountIn: "100000",                    // 100,000 sats in
  minAmountOut: "950000000000000000",    // your quote minus slippage
  fee: 3000,                             // 0.3% Uniswap V3 tier
  withdraw: true,                        // sweep output back to Spark
  useAvailableBalance: true,             // pull amountIn from the Spark wallet
});

console.log("submission id:", result.submissionId);
console.log("intent id:", result.intentId);

useAvailableBalance: true makes the SDK pull the input from your Spark wallet, run the swap, and dispatch the output back to Spark in one signed intent. Nothing needs to sit on the EVM side before or after.

What just happened

1. The SDK pulled 100_000 sats from your Spark wallet and sent them to the gateway’s deposit address.
2. It bundled that Spark transfer id, the Conductor swap call, and the USDB withdrawal into one canonical intent and signed it with your identity key.
3. The gateway admitted the intent. The sequencer included it once the deposit oracle confirmed the Spark transfer. Validators finalized the block.
4. SparkGateway emitted a SparkWithdrawal event for the USDB output. The settlement layer scanned the log and dispatched the matching Spark token transfer back to your Spark wallet.

The result returns once the intent reaches finalized. If you need to follow status changes, see Intents.

Next steps

Deposits

Move sats and Spark tokens in without swapping.

Withdrawals

Sweep balances back to Spark on demand.

Deploy your own contract

Sign and submit arbitrary EVM transactions through ExecutionClient.execute.

Reading state

Token info, balances, allowances, fees.