Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

/v3/limit - Place an order

Price a pair, build the artifact the wallet signs, and submit the signature or deposit hash that puts the order on the book.

Steps 1–3 of the order flow. Read Signing models first: which of the two shapes /v3/limit/build returns decides most of what this page asks you to handle.

Once an order is resting, Manage and cancel orders covers reading and cancelling it.

Placing a limit order. 1: POST /v3/limit/quote. 2: POST /v3/limit/build, which returns either typedData for the wallet to sign or tx for the wallet to broadcast; if isApproved is false, broadcast approvalTx first. 3: POST /v3/limit/submit with the signature or the depositTxHash. The order then rests until it is filled, cancelled or expires. Steps 4 to 7 read and cancel orders.
Steps 1–3 on this page.

1. Price the pair

Method: POST URL: https://api.swapkit.dev/v3/limit/quote

Prices the pair, measures the limit against the market, and returns a routeId for /v3/limit/build.

Request schema

Parameter
Type
Required
Description

sellAsset

string

Yes

Asset to sell, e.g. "ETH.ETH".

buyAsset

string

Yes

Asset to buy, e.g. "BTC.BTC".

sellAmount

decimal string

No

Send any two of sellAmount / buyAmount / limitPrice; the third is derived. Human-readable, not base units: 10 USDT is "10".

buyAmount

decimal string

No

Same rules as sellAmount.

limitPrice

decimal string

No

buyAsset per 1 sellAsset.

sourceAddress

string

No

Screened for AML now, and pre-filled into the /v3/limit/build request.

destinationAddress

string

No

Same as sourceAddress.

affiliateFee

int (0–1000 bps)

No

Overrides the API key's default. 0 when your key has no affiliate set up for the routed provider. NEAR Intents allows about 480 bps of fees in total.

expiresAt

int (unix seconds)

No

Only pre-fills the /v3/limit/build request; not checked here. Defaults to now + 3 days.

providers

enum[]

No

Restrict routing to these providers. Only ONEINCH, HARBOR and NEAR run limit orders; other provider names are skipped.

Asset identifiers follow the same nomenclature as the rest of the API — Chain.Asset ("BTC.BTC") or Chain.Asset-ContractAddress ("ETH.USDC-0xA0b8…"). See /tokens.

Response schema

Top level

Field
Type
Description

quoteId

string

UUID of this quote.

routes

LimitRoute[]

Always one route.

Per route

Field
Type
Description

routeId

string

UUID of this route. Pass it to /v3/limit/build.

provider

enum

The provider SwapKit chose.

sellAsset, buyAsset

string

Echoed from the request.

sellAmount, buyAmount, limitPrice

decimal string

Resolved values, including the one you didn't send.

spotPrice

decimal string

Current market price.

effectiveFillPrice

decimal string

The price the market must reach for the order to fill: spotPrice plus the fee gap. The gap is takerFeeBps + integratorFeeBps on 1inch and takerFeeBps on Harbor. NEAR Intents reports takerFeeBps: 0, so there it equals spotPrice. Compare limits against this, not spotPrice.

takerFeeBps

number

The provider's taker fee, in bps. Excludes integratorFeeBps.

spotPriceDeviationBps

number

Signed bps distance of limitPrice from effectiveFillPrice. Positive: the order rests until the market moves. Zero or negative: it fills immediately, at a worse rate than a market swap.

minExpirationSeconds, maxExpirationSeconds

number

Allowed range for expiresAt − now at /v3/limit/build. Today: from 60 s (1inch, Harbor) or 300 s (NEAR Intents) up to one year.

integratorFeeBps

number

Your affiliate fee on this route.

warnings

Warning[]

nextActions

object[]

One entry: the /v3/limit/build request, ready to send. If you didn't send addresses, replace its placeholder addresses first.

Warnings

warnings[] is always present, may be empty, and carries through to the /v3/limit/build response. At most one price warning fires per quote:

  • limitPriceBelowSpot — spotPriceDeviationBps ≤ -100. The limit is 1% or more below effectiveFillPrice, so the order fills immediately at a clearly worse rate than a market swap.

  • limitPriceWithinFeeGap — -100 < spotPriceDeviationBps ≤ 0, with a non-zero fee gap. It also fills immediately, only modestly off-market. Raising the limit by |spotPriceDeviationBps| bps or more makes it rest.

Both mean the order fills on submission rather than resting, so show them before the user signs. One more warning is independent of price:

  • limitOrderNotionalTooSmall — the sell-side USD value is below what the provider's fillers usually take (NEAR Intents: about $20). The order rests, but may never fill before it expires and is refunded. Skipped when the sell asset has no USD price.

Warnings never block anything. Whatever warnings[] holds, the quote stays valid and the order placeable — if a user should stop and reconsider, that gate has to live in your own UI.

Rendering a warning

  • display — a short label for the user, already carrying this quote's numbers. Show it as-is.

  • tooltip — a longer explanation for a hover or tap. Optional.

  • code — for your logic, such as asking for a second confirmation on limitPriceBelowSpot. An open enum: fall back to display for codes you don't know.

Errors

Status
Error code
Scenario

400

validation_error

Invalid body: not exactly two of sellAmount / buyAmount / limitPrice, a malformed or zero amount, sellAsset equal to buyAsset, or an unknown providers value. The message names the field.

400

insufficientLiquidity

No market rate for the pair, or a zero one. Retry.

400

invalidSourceAddress

sourceAddress isn't valid on the sell chain.

400

invalidDestinationAddress

destinationAddress isn't valid on the buy chain.

400

Other address codes

invalidSellAssetAddress, invalidBuyAssetAddress, xrpAddressRequiresTag, litecoinMwebAddressUnsupported: an address breaks a chain-specific rule.

400

limitOrderUnsupportedPair

No provider supports this pair.

400

limitOrderProviderUnsupported

providers names none of ONEINCH, HARBOR or NEAR, or is empty.

400

Provider codes (NEAR Intents)

NEAR Intents' own rejection, such as quoteError for an amount below its minimum.

401

apiKeyInvalid

Missing x-api-key.

401

unauthorized

Unrecognised x-api-key.

451

isSanctionedAddress

An address is on a sanctions or risk list.

502

limitOrderProviderError

1inch failed while pricing (rate limit, 5xx or transport). Retry.

503

limitOrderActionUnavailable

The action is switched off for one of the pair's chains. Can clear without a change on your side.


2. Build the signing artifact

Method: POST URL: https://api.swapkit.dev/v3/limit/build

Screens both addresses, builds the order with the provider, checks the token approval, and saves the order as PENDING.

Request schema

Parameter
Type
Required
Description

routeId

string

Yes

From /v3/limit/quote.

sourceAddress

string

Yes

Address on the sell chain that funds the order. Becomes maker.

destinationAddress

string

Yes

Address on the buy chain that receives the proceeds. Becomes receiver.

expiresAt

int (unix seconds)

Yes

An absolute time, but expiresAt − now must fall within the quote's [minExpirationSeconds, maxExpirationSeconds].

allowPartialFill

bool

No

1inch only, and must stay true (the default). Harbor and NEAR Intents ignore it.

allowMultipleFills

bool

No

Same as allowPartialFill.

Build response schema

Field
Type
Description

orderId

string

UUID of the order. Pass it to every later call.

orderHash

string

The provider's order identifier: 0x-prefixed on 1inch and Harbor, the 1Click order id on NEAR Intents.

typedData

object or null

Payload for the wallet to sign. Signed-intent orders only, otherwise null. See below.

tx

varies, or null

Transaction to broadcast. Deposit orders only, otherwise null. See below.

txMeta

object or null

How to broadcast tx; null when tx is. See below.

depositAddress

string (optional)

Harbor and NEAR Intents only. Where the funds land — informational; fund the order by broadcasting tx. See below.

depositAmount

decimal string (optional)

Harbor and NEAR Intents only. Exactly what tx deposits, human-readable. See below.

depositMemo

string (optional)

Every Harbor order, and NEAR Intents on Stellar: the memo that ties the deposit to the order. See below.

isApproved

boolean (optional)

Whether the token allowance is in place. Omitted when no approval applies. See below.

approvalTx

object (optional)

Approval to broadcast before the order. See below.

warnings

Warning[]

Carried over from the quote.

nextActions

object[]

The /v3/limit/submit request to send next.

Response — the two signing models

You get exactly one of these two shapes — see signing models.

1inch, selling a token.

The wallet signs typedData, then you post the resulting signature to /v3/limit/submit as { orderId, signature }.

Harbor and NEAR Intents, and 1inch selling a native gas asset. The example is a Harbor ETH deposit. A 1inch native sell has the same shape minus depositAddress, depositAmount, depositMemo, txMeta.memo and isApproved: its tx calls 1inch's native-order factory, which escrows the sell amount for the order.

The wallet signs and broadcasts tx, then you post the on-chain hash to /v3/limit/submit as { orderId, depositTxHash }.

The typedData object

An EIP-712 document (domain, types, primaryType, message). Pass it to the wallet unmodified: the signature covers the exact payload.

On 1inch the domain is "1inch Aggregation Router" version "6", and its verifyingContract is the same spender the approvalTx approves.

The tx field

Its shape depends on the sell chain, and txMeta says how to handle it, as on /v3/swap:

Field
Type
Description

txMeta.txType

string

How to sign and broadcast tx. "evm" is { from, to, value, data }, with value in wei as hex on a 1inch native sell and as a decimal string on Harbor and NEAR Intents — accept both. "psbt" is a base64 string. Other values name their chain ("solana", "near", "tron", …). An open enum: refuse an unknown value rather than guess.

txMeta.chainId

number (optional)

EVM chain id as a number (1, 42161). Only when txType is "evm".

txMeta.memo

string (optional)

The order memo inside tx, to check before signing. Same as depositMemo; omitted when there's none.

The deposit fields

Fund the order by broadcasting tx. depositAddress, depositAmount and depositMemo are informational: show them, and check tx against them before signing. A 1inch native sell returns none of them.

They are not a recipe for a transfer you build yourself: a plain transfer to depositAddress carries no memo and can't be matched to the order.

What ties a deposit to its order differs by route:

Route
The order is identified by
Does depositAddress repeat across orders?

NEAR Intents

A fresh depositAddress, minted on every /v3/limit/build — even for the same maker and pair.

Never. Sending to a previous order's address credits that order.

Harbor

The o: memo, returned as depositMemo, that tx carries — an argument to Harbor's router call on Ethereum, an OP_RETURN output on Bitcoin.

Always: it is Harbor's shared vault, which can also rotate between builds.

Stellar on NEAR Intents

depositMemo (MEMO_TEXT) alone — mandatory, and unique per order.

Always: one address is shared across orders.

So don't cache an address or a memo, and don't key either by maker or by pair.

Send exactly depositAmount. Overpaying doesn't enlarge the order — the excess is refunded separately after the order resolves. Underpaying leaves it unfunded.

Why isn't tx addressed to depositAddress?

On several routes it legitimately targets something else, so don't reject a deposit on that alone:

  • Harbor on EVM — tx calls Harbor's router, which forwards the value to the vault at depositAddress with the memo attached.

  • TON — tx.messages[0].address is your own jetton wallet, carrying a little TON for gas. The real destination and amount are inside the base64 payload.

  • NEAR — a token deposit calls the token's contract. Only a native NEAR.NEAR deposit is a plain transfer to depositAddress.

tx is built against chain state — a recent blockhash, a nonce, selected UTXOs — and a wallet prompt left sitting, or a hardware-wallet flow, routinely outlives it.

The approvalTx object

Present when the maker's token allowance is below the order amount. Same shape as on /v3/swap. Broadcast it and wait for confirmation before signing or broadcasting the order.

Field
Type
Description

approvalTx.to

string

Token contract.

approvalTx.from

string

The user's wallet.

approvalTx.value

string

Always "0".

approvalTx.data

string

Encoded approve() call.

approvalTx.gasLimit

string

Optional. Gas limit, as a hex quantity.

approvalTx.gasPrice

string

Optional. Legacy (type-0) gas price in wei, as a hex quantity.

The isApproved field

Only present when a token approve() is part of the flow:

Value
Meaning

isApproved: true

Nothing to broadcast — but not proof the allowance exists (see below).

isApproved: false

Broadcast approvalTx before signing the order.

Field omitted

No approval needed: a native sell, or a chain without allowances, such as a UTXO chain.

Tokens pulled through a router contract need an approval: 1inch, and Harbor's ETH.USDT deposits. NEAR Intents is funded by a plain transfer, so it never needs one, even for an ERC-20.

Why can isApproved be false for a token that's already approved?

It reports whether this order can be pulled, on the same amount- and spender-scoped terms as /v3/swap — see How the allowance is read. Approving 1 USDT and then building a 2 USDT order returns false, and an allowance granted for another provider doesn't carry over, because each provider pulls through its own contract.

It's advisory the other way too: if the allowance read fails, the build returns true rather than failing.

Errors

Status
Error code
Scenario

404

limitOrderQuoteNotFound

Unknown or expired routeId — routes last a few minutes. Quote again.

400

validation_error

Invalid body. The message names the field.

400

limitOrderExpirationOutOfBounds

expiresAt is outside the quote's expiration bounds. The message gives both.

400

limitOrderUnsupportedFillFlags

1inch: allowPartialFill or allowMultipleFills was false.

400

limitOrderUnsupportedPair

The provider can't build this pair. On 1inch: neither 1inch nor your key puts a fee on it, which 1inch orders can't express. Don't retry as-is.

400

limitOrderUnsupportedChain

The provider can't build on the sell chain, e.g. a 1inch native sell where 1inch has no native-order factory.

400

invalidSourceAddress, invalidDestinationAddress

An address isn't valid on its chain. /build re-checks both.

400

insufficientBalance

UTXO chains, Cardano, Sui and Tron: the maker address is empty, so there's nothing to build the deposit from. Fund it and rebuild.

400

sellAssetAmountTooSmall

Below the provider's minimum order size, given in the message. Unlike the limitOrderNotionalTooSmall warning, this blocks.

400

limitOrderRejected

The provider refused the order; the message gives its reason. On NEAR Intents, includes a delivery fee above 5% of the proceeds: place a larger order.

401

apiKeyInvalid, unauthorized

Missing or unrecognised x-api-key.

451

isSanctionedAddress

The full address screen flagged sourceAddress or destinationAddress.

500

limitOrderBuildFailed

The provider failed to build the order. On NEAR Intents, also fees above about 480 bps in total: lower affiliateFee.

502

limitOrderProviderError

NEAR Intents failed upstream (5xx or transport). Retry.


3. Submit the signed artifact

Method: POST URL: https://api.swapkit.dev/v3/limit/submit

Attaches the signature or the deposit tx hash and moves the order from PENDING to SUBMITTED. Sync moves it on to OPEN once the provider confirms it.

Request schema

Send signature or depositTxHash, depending on which artifact /v3/limit/build returned.

Parameter
Type
Required for
Description

orderId

string

All orders

From /v3/limit/build.

signature

string

Signed intent

Wallet signature over typedData. Relayed to the provider's orderbook.

depositTxHash

string

Deposit

Hash of the deposit transaction, exactly as the chain reports it. Comes back as depositHash on the order. Harbor lowercases it; NEAR Intents and 1inch store it as sent. See below.

Submitting a deposit hash

A deposit order submits the hash, never a signature — even on Solana, where a transaction's signature is its identifier.

Send it exactly as the chain reports it. Solana's hash is base58 and TON's base64, both case-sensitive: lowercasing them, a habit from EVM, destroys the value, and the deposit is never matched to the order.

Submit response schema

Field
Type
Description

orderId

string

UUID of the order.

orderHash

string

Same as on /v3/limit/build.

status

enum

Always SUBMITTED on success. See the order status lifecycle.

createdAt

ISO 8601 string

When the order was created.

Submit errors

Only 502 is worth retrying; the 4xx errors are client-side.

Status
Error code
Scenario

451

limitOrderMakerBlacklisted

The orderbook blocks this maker address — an upstream compliance decision, not SwapKit's screening. Permanent for the address.

400

limitOrderInsufficientAllowance

Allowance too low for the limit-order router. Rebuild, broadcast the returned approvalTx, then submit again.

400

limitOrderMaxOrdersExceeded

The maker is at the orderbook's open-order cap (1inch: 100). Cancel one first. The message gives the cap.

409

limitOrderInvalidState

The order is past PENDING or expired, or a signature was sent for a deposit order. On Harbor and NEAR Intents the deposit may already have advanced it: read the order, it's live.

404

limitOrderNotFound

Unknown orderId.

401

unauthorized

The order belongs to another API key.

400

validation_error

No signature or depositTxHash, or an empty one.

400

limitOrderRejected

Any other orderbook rejection — bad signature, expired, insufficient balance. The message gives the reason.

502

limitOrderSubmissionFailed

The orderbook failed upstream (5xx or transport). Retry.

Last updated