@swig-wallet/developer-sdk

API-key SDK for preparing Swig wallet operations on a server and signing the prepared transaction from a client.

Flow

The SDK is prepare-first:

1. Your server creates a SwigClient with an API key.
2. Your server prepares a wallet operation and receives one or more unsigned transactions.
3. Your client signs any transactions that require client authority.
4. Your app submits the ordered transactions directly or through a backend sponsor endpoint.

Framework Proxy Routes

If your app only needs an API-key proxy and does not need to inspect or modify prepared transactions, use the framework route helpers:

• Next.js
• NestJS

Server-Side TypeScript SDK

Use the TypeScript server SDK when you want control over the route shape, auth context, request validation, response format, or any transaction massage before returning a prepared payload to the client.

Create an API key from the Swig dashboard.

import { SwigClient } from '@swig-wallet/developer-sdk/server/typescript';

const swig = new SwigClient({
  apiKey: process.env.SWIG_API_KEY!,
  network: 'mainnet',
});

By default the SDK talks to https://backend.prod.infra.onswig.com. Override it with baseUrl:

const swig = new SwigClient({
  apiKey: process.env.SWIG_API_KEY!,
  baseUrl: 'http://localhost:8080',
  network: 'devnet',
});

Create Wallet

const created = await swig.wallets.create({
  feePayer,
  initialUser: {
    ed25519: {
      publicKey: userPublicKey,
    },
  },
});

return {
  wallet: created.wallet,
  transactions: created.transactions,
  transactionsToSign: created.clientAuthorityTransactions,
};

If policyId is omitted, the backend can create a no-recovery policy from an inline initialUser. For a passkey initial user, provide the secp256r1 public key:

const created = await swig.wallets.create({
  feePayer,
  initialUser: {
    secp256r1: {
      publicKey: passkeyPublicKey,
    },
  },
});

return {
  wallet: created.wallet,
  transactions: created.transactions,
  clientAuthorityTransactions: created.clientAuthorityTransactions,
  operatorSignedTransactions: created.operatorSignedTransactions,
  feePayerOnlyTransactions: created.feePayerOnlyTransactions,
};

Wallet creation returns transactions in the order they should be submitted. For recovery-enabled create flows, the create transaction is fee-payer only, the add-authority transaction is signed by the initial user, and the configure-recovery transaction is signed by the backend recovery operator before it is returned. Submit each transaction in order after applying any required client authority signature. A prepared transaction needs a client authority signature when signatureRequests.length > 0.

Prepare Grouped Operations

Use wallet.prepare when multiple operations should be built into one backend shaped transaction. The backend decides the final instruction layout and derives token accounts for token transfers.

const prepared = await wallet.prepare({
  feePayer,
  operations: [
    {
      type: 'transferSol',
      destination,
      amount: 1_000_000n,
    },
    {
      type: 'transferToken',
      mint,
      destinationOwner,
      amount: 10_000n,
    },
  ],
});

return {
  wallet: prepared.wallet,
  transactions: prepared.transactions,
  clientAuthorityTransactions: prepared.clientAuthorityTransactions,
  feePayerOnlyTransactions: prepared.feePayerOnlyTransactions,
};

Build a Custom Transaction

Use wallet.buildTransaction when the application supplies the raw Solana instructions. The backend wraps them in the Swig signing flow and returns an unsigned transaction; signing and submission remain client-side.

const prepared = await wallet.buildTransaction({
  feePayer,
  instructions: [
    {
      programId,
      accounts: [{ pubkey: destination, isWritable: true }],
      data: instructionData,
    },
  ],
  addressLookupTableAccounts,
});

Prepare SOL Transfer

const wallet = swig.wallets.use({
  swigConfigAddress,
  walletAddress,
  requesterAuthority: {
    ed25519: {
      publicKey: userPublicKey,
    },
  },
});

const preparedTransfer = await wallet.transfer.sol({
  feePayer,
  destination,
  amount: 1_000_000n,
});

return preparedTransfer;

Prepare Token Transfer

Token transfers derive backend-only fields such as token program, source ATA, destination ATA, and destination ATA creation:

const preparedTokenTransfer = await wallet.transfer.token({
  feePayer,
  mint,
  destinationOwner,
  amount: 10_000n,
});

return preparedTokenTransfer;

Prepare Swap

const preparedSwap = await wallet.swap.jupiter({
  feePayer,
  inputMint: 'So11111111111111111111111111111111111111112',
  outputMint: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
  amount: 10_000n,
  slippageBps: 100,
  destinationAccount,
  wrapAndUnwrapSol: true,
});

// destinationAccount is the recipient owner. The backend derives the output
// token ATA for SPL outputs or the native destination for unwrapped SOL.
return preparedSwap;

Add Funds With Ramp

Use swig.ramp to build a headless Add Funds UI. The server SDK keeps the developer API key server-side while returning frontend-safe quotes, launch URLs, and transaction history.

const quotes = await swig.ramp.quote({
  customer: {
    partnerApplicationId,
    swigUserId,
    customerType: 'individual',
  },
  wallet: {
    walletId,
    walletAddress,
    network: 'devnet',
  },
  direction: 'onramp',
  sourceAmount: '100.00',
  sourceCurrencyCode: 'USD',
  destinationCurrencyCode: 'USDC_SOLANA',
  countryCode: 'US',
  paymentMethodType: 'credit-debit-card',
});

const session = await swig.ramp.createSession({
  customer: {
    partnerApplicationId,
    swigUserId,
    customerType: 'individual',
  },
  wallet: {
    walletId,
    walletAddress,
    network: 'devnet',
  },
  direction: 'onramp',
  selectedQuoteId: quotes.quotes[0].quoteId,
  sourceAmount: '100.00',
  sourceCurrencyCode: 'USD',
  destinationCurrencyCode: 'USDC_SOLANA',
  countryCode: 'US',
  serviceProvider: quotes.quotes[0].serviceProvider,
  paymentMethodType: quotes.quotes[0].paymentMethodType,
  redirectUrl: 'https://app.example/ramp/return',
});

return {
  launchUrl: session.launchUrl,
};

Browser apps can call the local proxy surface with SwigBrowserClient:

import { SwigBrowserClient } from '@swig-wallet/developer-sdk/browser';

const swig = new SwigBrowserClient({ network: 'devnet' });

const history = await swig.ramp.listTransactions({
  walletId,
  direction: 'onramp',
  limit: 25,
});

Client Signing

Client code should only sign prepared transactions. It should not hold the API key or call the Swig backend directly.

One Business Grant Access

Use this when a local app needs an admin to grant one of the app's keys access to an existing One Business Swig. The local app sends the admin to One Business, then reads the result on its callback page.

import {
  buildOneBusinessGrantAccessUrl,
  completeOneBusinessGrantAccess,
} from '@swig-wallet/developer-sdk/browser';

const grantUrl = buildOneBusinessGrantAccessUrl({
  swigPubkey,
  authorityPublicKey: appAuthorityPublicKey,
  appName: 'Local Trading App',
  redirectUri: 'http://localhost:5173/swig/grant/callback',
  state: crypto.randomUUID(),
  actions: [
    {
      type: 'transferToken',
      mint: usdcMint,
      amount: '10000000',
      cadence: 'daily',
    },
  ],
});

window.location.assign(grantUrl);

// In /swig/grant/callback:
const grant = completeOneBusinessGrantAccess(window.location.href);
// grant.roleId and grant.walletAddress identify the newly granted authority.

Solana Transaction Signing

Use this for prepared transactions whose requester authority is Ed25519.

import {
  signPreparedTransaction,
  type PreparedTransaction,
} from '@swig-wallet/developer-sdk/client';
import { VersionedTransaction } from '@solana/web3.js';

declare const prepared: PreparedTransaction;

const signed = await signPreparedTransaction(prepared, {
  signTransaction: async (transaction) => {
    const versioned = VersionedTransaction.deserialize(
      Buffer.from(transaction, 'base64'),
    );
    versioned.sign([userKeypair]);
    return Buffer.from(versioned.serialize()).toString('base64');
  },
});

Passkey Transaction Signing

Use this for any prepared transaction whose signatureRequests contains a secp256r1 request. The same pattern applies to create, transfer, token transfer, and swap. See examples/passkey/server.ts and examples/passkey/client.ts for the split server/client flow.

import {
  createSecp256r1PasskeySigningFn,
  signPreparedSwigTransaction,
  signPreparedSwigTransactions,
  type PreparedTransaction,
} from '@swig-wallet/developer-sdk/client';

const passkeySigningFn = createSecp256r1PasskeySigningFn({
  allowCredentials: [{ id: credentialId, type: 'public-key' }],
  userVerification: 'preferred',
});

// The client SDK only signs. Your app owns fetching or passing in the prepared
// payload returned by the server-side SDK.
//
// const prepared = await fetch('/your-app-prepare-route', ...).then((response) =>
//   response.json(),
// );
declare const prepared: PreparedTransaction;

const signed = await signPreparedSwigTransaction(prepared, {
  secp256r1: passkeySigningFn,
});

declare const created: { clientAuthorityTransactions: PreparedTransaction[] };
const signedCreateTransactions = await signPreparedSwigTransactions(
  created.clientAuthorityTransactions,
  { secp256r1: passkeySigningFn },
);

EVM Transaction Signing

Use this when the prepared transaction contains a secp256k1 signature request. The helper wraps an EIP-1193 provider with personal_sign and adds the Ethereum message prefix expected by Swig's secp256k1 authority payload.

import {
  createSecp256k1EvmSigningFn,
  signPreparedSwigTransaction,
  type PreparedTransaction,
} from '@swig-wallet/developer-sdk/client';

declare const prepared: PreparedTransaction;
declare const evmAddress: string;

const evmSigningFn = createSecp256k1EvmSigningFn({
  provider: window.ethereum,
  address: evmAddress,
});

const signed = await signPreparedSwigTransaction(prepared, {
  secp256k1: evmSigningFn,
});

After signing, pass signed to your app-owned send or sponsor flow. On your server, swig.transactions.sponsor(signed) handles the deployed paymaster route and base58 payload encoding expected by the backend. Pass idempotencyKey when the application may retry sponsorship; a matching retry returns the original paymaster response.

For wallet creation, sign only created.clientAuthorityTransactions on the client. Do not authority-sign created.operatorSignedTransactions; those already include the backend recovery operator signature and only need the final fee-payer or sponsor signature before submission.

Recovery Flow

Recovery-enabled wallets should be created from a recovery-enabled policy. Pass the guardian once at wallet creation; the SDK returns a recoverySetup plan that can be fed directly into the setup helper.

const created = await swig.wallets.create({
  feePayer,
  policyId,
  initialUser: {
    secp256r1: {
      publicKey: passkeyPublicKey,
    },
  },
  recovery: {
    guardianPubkey: guardianPublicKey,
    delaySeconds: 86_400,
  },
});

Submit the creation transaction, then prepare the recovery setup from the plan returned by create. The add-authority transaction is signed by the current passkey authority; the configure-recovery transaction is already signed by Swig's recovery operator and only needs the fee payer or sponsor path.

import { signPreparedSwigTransaction } from '@swig-wallet/developer-sdk/client';

await submitPrepared(created.creationTransaction!);

const wallet = swig.wallets.use(created.wallet);

const setup = await wallet.recovery.prepareSetup({
  feePayer,
  ...created.recoverySetup!,
});

const signedAddAuthority = await signPreparedSwigTransaction(
  setup.addAuthorityTransaction!,
  { secp256r1: passkeySigningFn },
);

await submitPrepared(signedAddAuthority);
await submitPrepared(setup.configureRecoveryTransaction!);

After setup, the guardian can start recovery and execute after the configured delay. The current wallet authority can cancel a pending recovery.

import { signPreparedTransaction } from '@swig-wallet/developer-sdk/client';

declare const signWithGuardian: Parameters<
  typeof signPreparedTransaction
>[1]['signTransaction'];

const start = await wallet.recovery.start({
  feePayer,
  guardianPubkey: guardianPublicKey,
  newAuthority: newAuthorityPublicKey,
});
const signedStart = await signPreparedTransaction(start, {
  signTransaction: signWithGuardian,
});

const cancel = await wallet.recovery.cancel({
  feePayer,
});

const execute = await wallet.recovery.execute({
  feePayer,
  newAuthority: newAuthorityPublicKey,
});
const signedExecute = await signPreparedTransaction(execute, {
  signTransaction: signWithGuardian,
});

The guardian signs both start and execute. The current wallet authority signs cancel. Execute is prepared after the recovery delay has elapsed and applies the recovered authority change.

Public Entrypoints

• @swig-wallet/developer-sdk/server/typescript: API-key server SDK for manual transaction preparation.
• @swig-wallet/developer-sdk/client: client-only signing helpers.
• @swig-wallet/developer-sdk/server: server SDK aggregate exports.