Building a Liquidity Desk Integration

Who needs this

The Orkid Solver API is built for teams that need programmatic access to Orkid's routing and execution infrastructure. You should be reading this if:

• You execute >$1M/month in swap volume and need API access instead of a UI
• You run a treasury that rebalances between stablecoins and volatile assets
• You operate a payments platform that needs reliable on-ramp/off-ramp execution
• You're a market maker or prop desk that needs RFQ for inventory management
• You're building a wallet or dApp that wants Orkid routing under the hood

If you're an individual swapping $500 at a time, you don't need this. Use the UI at orkidlabs.xyz. This API is for teams that need automation, reliability, and scale.

How the integration works

The Orkid Solver API sits between your application and on-chain execution. Here's the flow:

1. 01

   Your app requests a route

   You call /v1/route with token in, token out, and amount. The solver computes the optimal route across all venues, including RFQ if the order qualifies.

2. 02

   Solver returns a quote

   The response includes the expected output amount, the route breakdown (hops, splits, venues), the adaptive slippage buffer, and a quote ID. The quote is valid for ~15 seconds.

3. 03

   Your user signs the swap

   Using Permit2, your user (or your treasury multisig) signs an EIP-712 message authorizing the swap. No gas, no on-chain transaction from the user. The signed message is sent back to the solver.

4. 04

   Solver executes on-chain

   Orkid's solver submits the execution transaction, pays gas, and manages MEV protection. The swap lands on-chain. Your user receives output tokens. You receive a transaction hash and execution receipt.

Solver API endpoints

Three endpoints cover the full integration:

All endpoints are REST over HTTPS. Base URL is https://api.orkidlabs.com. Requests require an API key in the X-Orkid-Key header.

Authentication and rate limits

Auth is simple: API key in a header. No OAuth, no JWT, no session management.

GET /v1/tokens HTTP/1.1
Host: api.orkidlabs.com
X-Orkid-Key: orkid_live_xxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

Rate limits by tier:

Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (Unix timestamp). If you exceed the limit, you get HTTP 429 with a Retry-After header.

Request and response format

Here's a full /v1/route request for a $500K USDC → WETH swap on Base:

POST /v1/route HTTP/1.1
X-Orkid-Key: orkid_live_xxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "chainId":   8453,
  "tokenIn":   "0x833589fCD6e6D0896C1dE0d0fA0Be8f3d53eB6E8",
  "tokenOut":  "0x4200000000000000000000000000000000000006",
  "amountIn":  "500000000000",
  "recipient": "0x{user_address}",
  "slippage":  "auto",
  "rfq":       true
}

And the response:

{
  "quoteId":       "0xabc123def456...",
  "chainId":       8453,
  "tokenIn":       "0x833589fCD6e6D0896C1dE0d0fA0Be8f3d53eB6E8",
  "tokenOut":      "0x4200000000000000000000000000000000000006",
  "amountIn":      "500000000000",
  "amountOut":     "195802763750000000",
  "route": [
    {
      "type":     "rfq",
      "filler":   "0x4808A1F195791Cc6E180cE92e1DD0A027851dFee",
      "share":    0.65
    },
    {
      "type":     "amm",
      "venue":    "uniswap_v3",
      "pool":     "0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640",
      "share":    0.35
    }
  ],
  "slippageBps":   0.41,
  "feeBps":        9,
  "expiresAt":     1735689700,
  "permit2Data":   "0x{signed_permit2_payload}"
}

Key fields:

• route: Array of route components. This example shows a hybrid — 65% filled via RFQ, 35% via Uniswap V3 AMM. The solver blended both for optimal price.
• slippageBps: The adaptive slippage buffer (0.41 bps for this route). Set "slippage": "auto" in the request to use adaptive; set a number to override (not recommended).
• feeBps: Always 9. The Orkid fee, embedded in the output amount.
• permit2Data: The unsigned Permit2 payload. Your user signs this, and you submit the signature to execute the swap.

Handling large orders ($1M+)

Large orders have different execution dynamics. Here's what changes at scale:

• RFQ becomes dominant. At $1M+, AMM price impact is 50–150 bps. RFQ fillers can quote 8–15 bps spreads. The solver automatically prefers RFQ for large orders. You don't need to change your request — just set "rfq": true.
• Multi-filler splitting. For orders above $1M, the solver may split across multiple RFQ fillers to reduce execution risk. Each filler quotes on their portion. The response route array will show multiple RFQ components with different filler addresses.
• Quote validity shrinks. Large orders get shorter quote windows (5–10 seconds vs 15 seconds for small orders) because fillers can't hold inventory risk for long. Your signing flow must be fast. For multisig treasury operations, pre-approve the Permit2 spend limit so signing is a single signature, not a multi-round ceremony.
• Slippage is tighter, not wider. RFQ orders get the minimum adaptive slippage buffer (~0.01 bps) because the price is quoted, not computed from pool state. This is counterintuitive but correct — RFQ eliminates pool price risk, so the buffer can be near-zero.

Monitoring and observability

For production integrations, you need to monitor three things:

1. 01

   API health

   Poll /v1/tokens every 30 seconds. If it returns 200, the API is up. If it returns 5xx or times out, switch to your fallback (direct AMM routing or another aggregator). Track response latency — if it exceeds 500ms, your quotes may be stale by the time you sign.

2. 02

   Execution success rate

   Track the ratio of successful swaps to attempted swaps. Orkid's baseline is >99.5%. If your rate drops below 98%, check: (a) are you signing within the quote window? (b) is your Permit2 approval still valid? (c) is Base congested? Most failures are client-side, not solver-side.

3. 03

   Price realization

   Compare the quoted amountOut to the actual on-chain received amount. The difference should be within the adaptive slippage buffer (typically < 1.25 bps). If realized slippage consistently exceeds the buffer, contact us — there may be a routing issue or a pool that's consistently stale.

Getting started

Ready to integrate? Here's the process:

• Email: jacob@orkidlabs.com
• Include: Team name, use case, expected monthly volume, chain(s), and whether you need RFQ access
• Timeline: API key provisioned within 48 hours of approval
• Onboarding: We provide a sandbox environment with test tokens on Base Sepolia for integration testing
• Production: Move to mainnet after successful sandbox testing. We monitor your first 100 swaps and provide a post-launch review.

We're selective about integrations — not because the API can't handle volume, but because we want to make sure your infrastructure is ready for production DeFi execution. If you're not sure whether you qualify, email us and we'll tell you straight.