SDK reference

The @orkid-labs/sdk package provides a typed client, Permit2 signing helpers, and a CLI for the Orkid Swap API.

Source: github.com/orkid-labs/orkid-sdk

Install

npm install @orkid-labs/sdk

Peer dependencies (only needed for signing):

npm install viem
# or
npm install ethers

The core SDK is dependency-free. The Permit2 signers are optional subpath exports — import OrkidViemPermitSigner from @orkid-labs/sdk/viem or OrkidEthersPermitSigner from @orkid-labs/sdk/ethers; each requires its corresponding peer installed.

Exports

Export	Description
`OrkidClient`	Main API client — `getQuote`, `solve`, `confirmTransaction`, `getAccount`, `getUsage`, `getRebates`
`SANDBOX_BASE_URL`	`'https://sandbox.orkidlabs.com'` — pass as `baseUrl` for the sandbox
`OrkidViemPermitSigner` (from `@orkid-labs/sdk/viem`)	Permit2 signing helper using a viem `WalletClient`
`OrkidEthersPermitSigner` (from `@orkid-labs/sdk/ethers`)	Permit2 signing helper using an ethers `Signer`
`ORKID_CHAIN_CONFIG`	Per-chain metadata (TVMExecutor, Permit2, RPC, explorer, min notional)
`PERMIT2`	Canonical Permit2 address: `0x000000000022D473030F116dDEE9F6B43aC78BA3`

Quick start — production

import { OrkidClient } from '@orkid-labs/sdk'
import { OrkidViemPermitSigner } from '@orkid-labs/sdk/viem'
import { createWalletClient, createPublicClient, http } from 'viem'
import { base } from 'viem/chains'
import { privateKeyToAccount } from 'viem/accounts'

const client = new OrkidClient({
  apiKey: process.env.ORKID_API_KEY!,
  // baseUrl defaults to https://orkidlabs.xyz
})

const account = privateKeyToAccount('0x...')
const walletClient = createWalletClient({ account, chain: base, transport: http() })
const publicClient = createPublicClient({ chain: base, transport: http() })
const permitSigner = new OrkidViemPermitSigner(walletClient, publicClient)

async function swapUsdcToWeth() {
  const quote = await client.getQuote({
    from: 'USDC',
    to: 'WETH',
    amount: '25.0',
    chain: 'base',
  })

  if (!quote.ok) throw new Error(quote.error)

  const { permit, signature } = await permitSigner.signSwap({
    user: account.address,
    fromToken: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
    fromDecimals: 6,
    amount: '25.0',
    chain: 'base',
  })

  const result = await client.solve({
    from: 'USDC',
    to: 'WETH',
    amount: '25.0',
    chain: 'base',
    user: account.address,
    permit,
    signature,
  })

  if (!result.ok) throw new Error(result.error)
  console.log('txHash', result.transaction?.txHash)
}

Quick start — sandbox

import { OrkidClient, SANDBOX_BASE_URL } from '@orkid-labs/sdk'

const sandbox = new OrkidClient({
  apiKey: process.env.ORKID_SANDBOX_KEY!,
  baseUrl: SANDBOX_BASE_URL, // https://sandbox.orkidlabs.com
})

// Same API surface — quotes are real, solves are always dry-run
const quote = await sandbox.getQuote({
  from: 'USDC',
  to: 'WETH',
  amount: '25.0',
  chain: 'arbitrum',
})

OrkidClient methods

Method	Description
`getQuote(params)`	Call `/api/v1/route`
`solve(params)`	Call `/api/v1/solve`
`dryRun(params)`	Call `/api/v1/solve` with `dryRun: true`
`confirmTransaction(txHash, chain)`	Call `/api/v1/confirm` for user-pays-gas swaps
`getAccount()`	Call `/api/v1/account`
`getUsage(params)`	Call `/api/v1/usage`
`getRebates(params)`	Call `/api/v1/rebates`
`listTokens(params)`	Call `/api/v1/tokens`
`getStatus()`	Call `/api/v1/status`
`getBridgeChains()`	Call `/api/v1/bridge/chains`
`getBridgeTokens(chainId)`	Call `/api/v1/bridge/tokens`
`getBridgeQuote(request)`	Call `/api/v1/bridge/quote`
`getBridgeStatus(params)`	Call `/api/v1/bridge/status`
`trackBridgeDeposit(request)`	Call `/api/v1/bridge/track`

Cross-chain bridge

The SDK exposes the full bridge flow. Bridging is non-custodial — the user signs the approval and deposit transactions directly; Orkid never holds funds and Permit2 is not involved.

// 1. Quote — depositor is the wallet that will sign
const res = await client.getBridgeQuote({
  originChainId: 8453,
  destinationChainId: 1,
  inputToken: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
  outputToken: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
  amount: '25000000',           // raw base units
  depositor: userAddress,
})

if (!res.ok) throw new Error(res.error)

// 2. Sign approvals then the deposit from the user's wallet
for (const tx of res.quote.approvalTxns) {
  await walletClient.sendTransaction({ to: tx.to, data: tx.data, chainId: tx.chainId })
}
const hash = await walletClient.sendTransaction({
  to: res.quote.swapTx.to,
  data: res.quote.swapTx.data,
  value: BigInt(res.quote.swapTx.value ?? '0'),
  chainId: res.quote.swapTx.chainId,
})

// 3. Register for tracking, then poll status
await client.trackBridgeDeposit({
  originChainId: 8453,
  destinationChainId: 1,
  depositor: userAddress,
  recipient: res.quote.recipient,
  inputToken: res.quote.inputToken.address,
  outputToken: res.quote.outputToken.address,
  amountInRaw: res.quote.inputAmount,
  expectedOutRaw: res.quote.expectedOutputAmount,
  quoteId: res.quote.id,
  originTxHash: hash,
})

const status = await client.getBridgeStatus({ depositTxnRef: hash })
// status.deposit.status → 'pending' | 'filled' | 'expired' | 'refunded'

Re-quote rather than submit if swapTx.simulationSuccess === false or the quote has expired. Refunds return to the depositor on the origin chain and can take a few hours — see Cross-chain bridge for the full endpoint reference and risk notes.

OrkidViemPermitSigner

The OrkidViemPermitSigner handles nonce discovery, Permit2 typed data construction, and signing using a viem WalletClient + PublicClient.

import { OrkidViemPermitSigner } from '@orkid-labs/sdk/viem'
import { createWalletClient, createPublicClient, http } from 'viem'
import { base } from 'viem/chains'
import { privateKeyToAccount } from 'viem/accounts'

const account = privateKeyToAccount('0x...')
const walletClient = createWalletClient({ account, chain: base, transport: http() })
const publicClient = createPublicClient({ chain: base, transport: http() })

const signer = new OrkidViemPermitSigner(walletClient, publicClient)

const { permit, signature, chainConfig } = await signer.signSwap({
  user: account.address,
  fromToken: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
  fromDecimals: 6,
  amount: '25.0',
  chain: 'base',
})

// permit — the PermitTransferFrom data (without spender)
// signature — 65-byte hex signature

See the Permit2 signing walkthrough for the manual flow.

Tests

The SDK includes a full test suite:

npm test              # unit + integration tests
npm run test:watch    # watch mode
ORKID_E2E=1 npm run test:e2e  # live API tests (hits orkidlabs.xyz)

Examples

See the examples/ directory in the SDK repo for complete, runnable examples:

examples/vanilla-viem.ts — full flow with a viem wallet client
examples/vanilla-ethers.ts — full flow with an ethers signer
examples/react.tsx — React hook wrapper
examples/nextjs-server-action.ts — server-side key protection in a Next.js app
examples/curl.sh — copy-paste curl commands

SDK reference

On this page