Orbs

The Orbs integration connects web3agent to the Orbs Protocol, which provides two distinct execution layers: Liquidity Hub for aggregated same-chain swaps, and Spot for on-chain conditional orders settled by a decentralized keeper network.

All Orbs tools use the orbs_ prefix. No API key or configuration is required.

Order Types

Liquidity Hub Swap

A market swap that aggregates liquidity across DEXs and runs a solver auction. Solvers compete to fill the order at the best price. Settlement is atomic and on-chain.

Best for: immediate execution at the best available price.

dTWAP (Time-Weighted Average Price)

Splits a large order into equal chunks executed at regular intervals. Reduces price impact on large trades by spreading execution over time.

Best for: large positions where a single market order would move the price.

dLIMIT

An on-chain limit order that executes when the market price reaches a target. Keepers monitor the price and fill the order when conditions are met.

Best for: entering or exiting a position at a specific price without watching the market.

Stop-Loss

A conditional Spot order that sells when the price drops below a trigger. Protects against downside by automatically exiting a position.

Best for: risk management on open positions.

Take-Profit

A conditional Spot order that sells when the price rises above a trigger. Locks in gains automatically.

Best for: capturing upside without needing to monitor prices manually.

Tools

Tool	Description
`orbs_get_quote`	Get a Liquidity Hub swap quote with expected output and price impact
`orbs_swap`	Execute a Liquidity Hub market swap
`orbs_twap`	Place a dTWAP order (split execution over time)
`orbs_limit`	Place a dLIMIT order (execute at target price)
`orbs_spot`	Place a Spot order (stop-loss or take-profit with trigger price)
`orbs_order_status`	Check the status of a Spot order by hash

SDK Functions

Import from "web3agent":

import {
  prepareSwapIntent,
  prepareTwapIntent,
  prepareLimitIntent,
  prepareOrderIntent,
  submitSignedSwap,
  submitSignedOrder,
  pollSwapStatus,
  getRequiredApprovals,
} from "web3agent";

Intent Preparation vs Direct Execution

The Orbs SDK follows a two-step pattern for browser wallet integrations:

Prepare the intent (returns EIP-712 typed data + required approvals)
Sign in the browser wallet
Submit the signed payload

For server-side execution with a private key, the MCP tools handle signing internally.

Examples

Get a Swap Quote

import { prepareSwapIntent } from "web3agent";

const intent = await prepareSwapIntent({
  fromToken: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // USDC on Base
  toToken: "0x4200000000000000000000000000000000000006",   // WETH on Base
  fromAmount: "100000000", // 100 USDC (6 decimals)
  chainId: 8453,
});

console.log(intent.quote.outAmount);    // expected WETH output
console.log(intent.quote.priceImpact);  // price impact percentage

Execute a Swap via MCP Tool

When an AI agent calls orbs_swap, it handles the full flow:

orbs_swap({
  fromToken: "USDC",
  toToken: "WETH",
  fromAmount: "100",
  chainId: 8453
})

The tool resolves token symbols to addresses, fetches a quote, signs with the configured wallet, and submits to the Orbs relay.

Place a dTWAP Order

import { prepareTwapIntent } from "web3agent";

const intent = await prepareTwapIntent({
  fromToken: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // USDC
  toToken: "0x4200000000000000000000000000000000000006",   // WETH
  fromAmount: "1000000000", // 1000 USDC total
  chunks: 10,               // split into 10 chunks
  fillDelay: 3600,          // 1 hour between chunks
  chainId: 8453,
});

Place a Stop-Loss Order

import { prepareOrderIntent } from "web3agent";

const intent = await prepareOrderIntent({
  fromToken: "0x4200000000000000000000000000000000000006", // WETH
  toToken: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",  // USDC
  fromAmount: "15000000000000000", // 0.015 WETH (18 decimals)
  outputTriggerLower: "34620000",  // trigger: 34.62 USDC per chunk (6 decimals)
  chainId: 8453,
});

Poll Order Status

import { pollSwapStatus } from "web3agent";

const result = await pollSwapStatus({
  orderHash: "0xabc...",
  chainId: 8453,
});

// result.status: "pending" | "eligible" | "filled" | "expired" | "failed" | "cancelled"

Checking Required Approvals

Before signing a Spot order, check whether token approvals are needed:

import { getRequiredApprovals } from "web3agent";

const approvals = await getRequiredApprovals({
  token: "0x4200000000000000000000000000000000000006", // WETH
  amount: "15000000000000000",
  owner: "0xYourWalletAddress",
  chainId: 8453,
});

// approvals: Array<{ token, spender, amount }>

Important Constraints

Native input tokens are not supported for Spot orders. The Spot contract (RePermit) does not accept ETH, BNB, or MATIC as input. Wrap to WETH, WBNB, or WMATIC first. Native output tokens are supported: use 0x0000000000000000000000000000000000000000 to receive native ETH.

Liquidity Hub swaps do support native input tokens. The integration wraps them automatically.

Trigger values are per-chunk output amounts, not prices. For a stop-loss selling 0.015 WETH at $2,308/ETH:

Trigger = 0.015 × 2308 = 34.62 USDC
In raw units: "34620000" (USDC has 6 decimals)

Minimum trade sizes:

Liquidity Hub swaps: ~$6-10 minimum (error code ldv = Low Dollar Value)
Spot orders: ~$30+ recommended for keepers to fill economically

Relay Environments

The Orbs relay has two environments:

Environment	URL
Development	`https://agents-sink-dev.orbs.network` (default)
Production	`https://agents-sink.orbs.network`

Override with the SPOT_API_URL environment variable. No rebuild required.

SPOT_API_URL=https://agents-sink.orbs.network npx web3agent

Order Status Reference

Status	Terminal?	Meaning
`pending`	No	Submitted, awaiting keeper pickup
`eligible`	No	Keeper found, price check in progress
`pending-price-check`	No	Price verification underway
`filled`	Yes	Order fully executed
`completed`	Yes	Order completed (alias for filled)
`cancelled`	Yes	Cancelled on-chain
`expired`	Yes	Order TTL elapsed without fill
`failed`	Yes	Execution failed
`rejected`	Yes	Rejected by keeper network