Quick start

This guide walks through the full swap flow: get a quote, approve Permit2, sign a permit, and execute.

1. Get an API key

Every programmatic request requires an X-ORKID-API-Key header. Keys are 40-character hex strings.

To get a key, contact api@orkidlabs.com or log in to the board admin and generate one for your partner account.

2. Get a quote

curl -X POST https://orkidlabs.xyz/api/v1/route \
  -H "X-ORKID-API-Key: <key>" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "USDC",
    "to": "WETH",
    "amount": "25.0",
    "chain": "base",
    "fromAddress": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
    "fromDecimals": 6,
    "toAddress": "0x4200000000000000000000000000000000000006",
    "toDecimals": 18
  }'

Response:

{
  "ok": true,
  "quote": {
    "amountIn": "25.000000",
    "amountOut": "0.010184",
    "amountOutRaw": "10183963710975259",
    "volumeUsd": 25,
    "rate": "0.000407 WETH/USDC",
    "protocol": "aerodrome_slipstreams",
    "priceImpactBps": 9.66
  },
  "gaslessEligible": true,
  "computeMs": 142
}

3. Approve Permit2 (one-time per token)

Before the first swap of each token, the user must approve the Permit2 contract:

IERC20(token).approve(PERMIT2, type(uint256).max)

Permit2 address on all chains: 0x000000000022D473030F116dDEE9F6B43aC78BA3

4. Sign a Permit2 message

Sign a PermitTransferFrom message with the TVMExecutor as the spender. See the Permit2 signing walkthrough for full details.

With the SDK:

import { OrkidClient, OrkidPermitSigner } from '@orkid/sdk'
import { createWalletClient, http } from 'viem'
import { base } from 'viem/chains'
import { privateKeyToAccount } from 'viem/accounts'

const client = new OrkidClient({ apiKey: process.env.ORKID_API_KEY! })
const account = privateKeyToAccount('0x...')
const walletClient = createWalletClient({ account, chain: base, transport: http() })
const permitSigner = new OrkidPermitSigner(walletClient)

const signed = await permitSigner.prepareAndSign({
  fromToken: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
  fromDecimals: 6,
  amount: '25.0',
  chain: 'base',
})

5. Execute the swap

const result = await client.solve({
  from: 'USDC',
  to: 'WETH',
  amount: '25.0',
  chain: 'base',
  user: account.address,
  fromAddress: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
  fromDecimals: 6,
  toAddress: '0x4200000000000000000000000000000000000006',
  toDecimals: 18,
  dryRun: false,
  permit: signed.permit,
  signature: signed.signature,
})

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