1inch Limit Order API: Complete Developer Guide

Centralized exchanges like Binance and OKX have had limit orders since forever. You set a price, walk away, and the order fills when the market gets there. DeFi traders were stuck with market orders and AMM slippage for years — until 1inch built their Limit Order Protocol. Now you can place limit orders on-chain that execute gaslessly, with no counterparty risk, and with enough programmability to build serious automated strategies around them.

The 1inch Limit Order API sits on top of that protocol, giving developers a clean REST interface to create, sign, and manage orders without writing raw smart contract calls. Whether you're building a personal trading bot or integrating DeFi order flow into a larger system, this is the tooling that makes it practical.

How the 1inch Limit Order Protocol Works

Before touching the API, it's worth understanding what you're actually building on. The 1inch Limit Order Protocol is an on-chain system where orders are signed off-chain (EIP-712 typed signatures) and stored in a decentralized orderbook. Fillers — third parties watching the orderbook — execute your order when market conditions match. You pay no gas until your order fills, and even then the filler often covers it.

This is fundamentally different from how Binance or Bybit handle limit orders. On those CEXs, the exchange custodies your funds and matches orders in their internal engine. With 1inch, your funds stay in your wallet, the order logic lives in an audited smart contract, and anyone can be a filler. The trust model is inverted — you trust math, not a company.

• Orders are EIP-712 signed messages — no gas to place them
• Funds remain in your wallet until execution
• Fillers compete to execute your orders, often covering gas
• Supports Ethereum, Polygon, BNB Chain, Arbitrum, Avalanche, and more
• Custom predicates allow conditional execution logic

Setting Up the 1inch Limit Order SDK

The 1inch limit order SDK is an npm package that handles all the heavy lifting: order construction, EIP-712 signing, and API calls. Start here before touching raw REST endpoints — the SDK saves you from a lot of ABI encoding headaches.

// Install the SDK
// npm install @1inch/limit-order-protocol-utils ethers

import { LimitOrderBuilder, LimitOrderProtocolFacade, Web3ProviderConnector } from '@1inch/limit-order-protocol-utils';
import { ethers } from 'ethers';

// Connect to Ethereum (or any supported chain)
const provider = new ethers.providers.JsonRpcProvider(process.env.RPC_URL);
const wallet = new ethers.Wallet(process.env.PRIVATE_KEY, provider);

// Chain ID — 1 for Ethereum mainnet, 137 for Polygon, 56 for BNB Chain
const chainId = 1;
const contractAddress = '0x119c71D3BbAC22029622cbaEc24854d3D32D2828'; // 1inch v3 on Ethereum

const connector = new Web3ProviderConnector(provider);
const limitOrderBuilder = new LimitOrderBuilder(contractAddress, chainId, connector);

console.log('SDK initialized for chain:', chainId);

The contract address changes per network and protocol version. Always verify the current address from the official 1inch documentation — using a stale address will cause silent failures that are painful to debug.

Use environment variables for your private key and RPC URL. Never hardcode credentials in source files, even for personal bots. A leaked key on GitHub can drain a wallet in minutes.

Creating and Signing a Limit Order

Creating an order with the 1inch limit order SDK involves three steps: build the order struct, sign it with your wallet, and submit it to the API. Here's a complete example buying USDC with ETH at a target price — the kind of order you'd place when you think ETH is going to dip and you want to catch the bottom without watching charts all day.

import axios from 'axios';

// Token addresses on Ethereum mainnet
const WETH = '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2';
const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';

// Build the order: sell 0.1 WETH, buy at least 300 USDC
const limitOrder = limitOrderBuilder.buildLimitOrder({
  makerAssetAddress: WETH,
  takerAssetAddress: USDC,
  makerAddress: wallet.address,
  makerAmount: ethers.utils.parseUnits('0.1', 18).toString(),  // 0.1 WETH
  takerAmount: ethers.utils.parseUnits('300', 6).toString(),    // 300 USDC minimum
  expireTime: Math.floor(Date.now() / 1000) + 86400,           // 24 hours
});

// Sign the order (EIP-712 — no gas, just a signature)
const limitOrderTypedData = limitOrderBuilder.buildLimitOrderTypedData(limitOrder);
const signature = await connector.signTypedData(wallet.address, limitOrderTypedData);

// Submit to 1inch orderbook
try {
  const response = await axios.post(
    `https://api.1inch.dev/orderbook/v4.0/${chainId}/order`,
    {
      orderHash: limitOrderBuilder.buildLimitOrderHash(limitOrderTypedData),
      signature,
      data: limitOrder,
    },
    {
      headers: {
        'Authorization': `Bearer ${process.env.ONEINCH_API_KEY}`,
        'Content-Type': 'application/json',
      }
    }
  );
  console.log('Order submitted:', response.data);
} catch (err) {
  if (err.response?.status === 400) {
    console.error('Order validation failed:', err.response.data.description);
  } else {
    console.error('API error:', err.message);
  }
}

The API key is required for production use — get one from the 1inch developer portal. Rate limits on the free tier are generous enough for personal bots, but anything with high order throughput will need a paid plan.

Querying and Managing Active Orders

Once orders are in the 1inch orderbook, you'll want to monitor them — check fill status, cancel stale orders, and react to market changes. The REST API gives you full visibility. Here's a Python example for querying all active orders for a wallet address, which slots nicely into monitoring scripts or a dashboard backend.

import requests
import os
from datetime import datetime

API_KEY = os.environ['ONEINCH_API_KEY']
WALLET = os.environ['WALLET_ADDRESS']
CHAIN_ID = 1  # Ethereum mainnet

BASE_URL = f'https://api.1inch.dev/orderbook/v4.0/{CHAIN_ID}'

headers = {
    'Authorization': f'Bearer {API_KEY}',
    'Accept': 'application/json',
}

def get_active_orders(wallet: str, page: int = 1, limit: int = 100) -> dict:
    """Fetch active limit orders for a wallet."""
    url = f'{BASE_URL}/address/{wallet}'
    params = {
        'page': page,
        'limit': limit,
        'statuses': '[1]',  # 1 = active, 2 = filled, 3 = expired, 4 = cancelled
    }
    resp = requests.get(url, headers=headers, params=params, timeout=10)
    resp.raise_for_status()
    return resp.json()

def cancel_order(order_hash: str) -> bool:
    """Cancel an order by hash (requires on-chain tx — costs gas)."""
    # Note: cancellation is done on-chain via contract call, not REST API
    # The API just removes it from the orderbook after on-chain cancel
    print(f'To cancel {order_hash}, call cancelOrder() on the protocol contract')
    return True

try:
    orders = get_active_orders(WALLET)
    print(f'Active orders: {len(orders)}')
    
    for order in orders:
        data = order.get('data', {})
        expiry = datetime.fromtimestamp(int(data.get('expiration', 0)))
        print(f"  Hash: {order['orderHash'][:16]}...")
        print(f"  Maker: {data.get('makerAsset', 'unknown')[:8]}...")
        print(f"  Expires: {expiry}")
        print()
except requests.HTTPError as e:
    print(f'HTTP {e.response.status_code}: {e.response.text}')
except requests.ConnectionError:
    print('Network error — check RPC and API connectivity')

One thing to internalize: cancelling a 1inch limit order on-chain costs gas, unlike cancelling on Binance or KuCoin where it's free. This shapes how you architect your bot — you want expiry times set sensibly so orders self-cancel rather than requiring manual gas spend to clean them up.

Integrating Trading Signals with Limit Orders

A limit order sitting at a static price is useful. A limit order placed dynamically in response to real-time signals is where the edge comes from. The pattern here is: consume a signal feed, decide whether to act, construct and submit an order. Platforms like VoiceOfChain provide real-time on-chain order flow signals — whale accumulation, large transfer alerts, exchange inflow/outflow — that map naturally to conditional limit order placement.

For example: VoiceOfChain detects a large ETH inflow to a cold wallet historically associated with accumulation. Your bot receives that signal, checks the current ETH price, and places a 1inch limit order 2% below spot to try to catch any resulting dip. The order expires in 4 hours. If the dip doesn't come, the order expires and you've spent nothing.

import asyncio
import aiohttp
from decimal import Decimal

ONEINCH_API_KEY = os.environ['ONEINCH_API_KEY']
CHAIN_ID = 137  # Polygon — lower gas costs for testing signal-driven bots

async def get_spot_price(token_in: str, token_out: str, amount_wei: int) -> Decimal:
    """Get current price via 1inch quote API."""
    url = f'https://api.1inch.dev/swap/v6.0/{CHAIN_ID}/quote'
    params = {
        'src': token_in,
        'dst': token_out,
        'amount': str(amount_wei),
    }
    async with aiohttp.ClientSession() as session:
        async with session.get(
            url,
            headers={'Authorization': f'Bearer {ONEINCH_API_KEY}'},
            params=params
        ) as resp:
            data = await resp.json()
            return Decimal(data['dstAmount']) / Decimal(amount_wei)

async def place_signal_order(signal: dict):
    """
    React to an incoming VoiceOfChain signal.
    signal = {'type': 'whale_accumulation', 'asset': 'ETH', 'confidence': 0.85}
    """
    if signal.get('confidence', 0) < 0.75:
        print('Signal confidence below threshold — skipping')
        return
    
    # Get current market price
    # In production, use actual token addresses for the chain
    spot = await get_spot_price(WETH_POLYGON, USDC_POLYGON, 10**18)
    
    # Place limit order 2% below spot (buy the dip)
    target_price = spot * Decimal('0.98')
    taker_amount_usdc = int(target_price * Decimal('0.1') * 10**6)  # For 0.1 ETH
    
    print(f"Signal received: {signal['type']}")
    print(f"Spot: ${spot:.2f} | Target: ${target_price:.2f}")
    print(f"Placing limit order: 0.1 ETH @ ${target_price:.2f}")
    
    # ... build and submit order using SDK as shown earlier
    # Order expires in 4 hours

# Simulate receiving a signal
asyncio.run(place_signal_order({
    'type': 'whale_accumulation',
    'asset': 'ETH',
    'confidence': 0.88
}))

Start on Polygon or Arbitrum for bot development — gas costs are a fraction of Ethereum mainnet, and the 1inch Limit Order Protocol is fully deployed on both chains. Move to mainnet once the strategy is proven.

Frequently Asked Questions

Where to Go From Here

The 1inch Limit Order API gives DeFi traders something CEX users have always had: the ability to set a price and walk away. But the programmability goes far beyond what Coinbase or Gate.io offer with their basic limit order UIs. Custom predicates let you build conditional logic — orders that only execute if another price condition is met, or if a specific block number has passed. That's territory no centralized exchange touches.

For most developers, the progression looks like this: start with the 1inch limit order SDK on a testnet, get comfortable with the order construction and signing flow, then move to Polygon mainnet for live but cheap testing. Add signal integration once you've validated the mechanical plumbing works. Platforms like VoiceOfChain become genuinely valuable at that stage — you're no longer placing orders based on gut feel, but reacting to quantified on-chain events. The API is the mechanism; the signal quality is the edge.

The code examples in this guide are starting points, not production-ready scripts. Rate limit handling, order state reconciliation, wallet nonce management, and monitoring all need thought before you deploy capital. But the core pattern — sign off-chain, submit to orderbook, let fillers execute — is solid, and the 1inch infrastructure is mature enough to build serious tooling on top of.