/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.
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
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.
Response schema
Top level
quoteId
string
UUID of this quote.
routes
LimitRoute[]
Always one route.
Per route
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.
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 beloweffectiveFillPrice, 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.
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 onlimitPriceBelowSpot. An open enum: fall back todisplayfor codes you don't know.
Errors
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
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
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.
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.
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:
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:
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.
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.
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:
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.
Errors
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.
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
orderId
string
UUID of the order.
orderHash
string
Same as on /v3/limit/build.
createdAt
ISO 8601 string
When the order was created.
Submit errors
Only 502 is worth retrying; the 4xx errors are client-side.
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

