Decision tables

Deterministic routing rules that map user intent, quote responses, wallet state, and errors to the next Velora action.

Use these tables when an agent needs to choose the next Velora action. Prefer explicit rules over model judgment, and branch on the data returned by the API rather than on assumptions from the prompt.

User intent → Velora surface

User intent	Prefer	Agent action	Why
”Swap token A to token B”	mode=ALL	Call GET /v2/quote with mode=ALL, chainId, token addresses, amount, slippage, and the app or project partner value.	Velora can choose the best available path.
”Gasless swap” or “I have no gas”	Delta	Call GET /v2/quote with mode=DELTA. Continue only if the response includes a delta block.	Delta uses an EIP-712 signature, a solver auction, and protocol settlement.
”Place a limit order” or “trade only if price reaches X”	Delta LIMIT order	Collect the target price, side, token pair, chain, amount, expiry, recipient, and partially-fillable preference before building the order.	New limit orders are Delta orders over the Delta API, not AugustusRFQ.
”TWAP this trade” or “split this order over time”	Delta TWAP	Collect side, total amount, number of slices, cadence/interval, chain, token pair, slippage/price constraints, deadline/expiry, recipient, and max source spend for buy TWAPs.	TWAP is one scheduled Delta order, not repeated independent swaps. Preserve sell-vs-buy amount semantics.
”Best price”	mode=ALL	Quote with mode=ALL, then branch on delta vs market.	Velora can choose the best available path.
”Protect me from MEV”	Delta	Call GET /v2/quote with mode=DELTA. Continue only if the response includes a delta block.	MEV protection is a Delta-only scenario.
”Swap now” or “settle in this transaction”	Market API	Call GET /v2/quote with mode=MARKET, then build a Market transaction.	Market returns calldata the user sends on-chain.
”Sell exactly this amount”	Sell quote	Treat the user amount as the source amount.	The user fixed input. Do not reinterpret it as a target output.
”Buy exactly this amount”	Buy quote	Treat the user amount as the destination amount and cap source spend.	The user fixed output. The agent should protect max spend.
”Embed swaps in my app”	SDK or Widget	Use the SDK for custom UX, or the Widget for fastest integration.	The agent should not build raw API plumbing when the requested job is app embedding.
”OTC” or “RFQ with a counterparty”	AugustusRFQ	Route to the AugustusRFQ flow.	AugustusRFQ is for OTC/RFQ settlement, not standard limit orders.

Use mode=ALL when the user has not explicitly chosen Delta or Market. A mode=ALL response returns one execution path. Do not expect both.

Quote response → next action

API result	Next action	Preserve	Do not
Top-level response field is delta	Continue the Delta order flow with POST /v2/delta/orders/build.	Pass the delta object and matching hmac from the same quote response.	Do not normalize, sort, round, or reconstruct the delta object.
Top-level response field is market	Continue the Market transaction flow with POST /transactions/:chainId.	Pass the returned market object into the transaction build step.	Do not try to submit it as a Delta order.
Response has neither delta nor market	Stop the flow and surface the no-route result.	Keep the user’s original tokens, chain, amount, and mode for retry suggestions.	Do not fabricate a quote, route, gas estimate, or output amount.
Quote expired, HMAC invalid, or build rejected	Requote, then rebuild from the fresh response.	Use the newest delta, hmac, or market object.	Do not reuse stale quote payloads.
Chain or token unsupported	Ask the user to choose a supported chain/token pair.	Link to chains and contracts when useful.	Do not guess a token address from symbol alone.

Wallet state → approval or signature

Wallet state	Agent action	Rule
Source token is native ETH	Skip ERC-20 approval.	Use 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE as the native token placeholder.
ERC-20 allowance is insufficient for Market	Ask the user to approve the Market spender, then rebuild or send the swap transaction.	Market execution uses Augustus v6.2 calldata.
ERC-20 allowance is insufficient for Delta	Ask the user to approve the Delta spender before submitting the order.	Do not approve Augustus for a Delta order.
Wallet can sign EIP-712	Use Delta when the quote response includes delta.	The user signs typed data, not an on-chain transaction.
Wallet cannot sign EIP-712	Ask whether to fall back to Market if a Market route is available.	Do not silently change execution mode.
Connected chain differs from quote chain	Ask the user to switch networks before signing or sending.	The chain used for quote, approval, signature, and execution must match.
Recipient is not the connected wallet	Ask for explicit confirmation.	Treat third-party recipients as a sensitive action.

Execution mode → signing behavior

Flow	User signs	User pays gas	Submit with	Track with
Market Swap	On-chain transaction	Yes	Wallet transaction send	Transaction hash
Delta Swap	EIP-712 typed data	No	POST /v2/delta/orders	Delta order ID and status
Delta LIMIT order	EIP-712 typed data from POST /v2/delta/orders/build	No at order creation	POST /v2/delta/orders with order=toSign.value, signature, type=LIMIT, chainId, and partner	Order ID and fill status
Delta TWAP	EIP-712 typed data from POST /v2/delta/orders/build	No at order creation	POST /v2/delta/orders after signing the built TWAPOrder or TWAPBuyOrder payload	Slice execution and order status
AugustusRFQ OTC flow	RFQ order or fill transaction, depending on the integration	Depends on fill path	AugustusRFQ flow	RFQ order/fill state

Order type → required details

Order type	Agent must collect	Agent must preserve
Market or Delta Swap	Chain, source token, destination token, amount, direction, recipient, slippage.	The selected execution mode and the quote response object used for build.
Limit order	Chain, token pair, side, amount, target price, expiry/deadline, recipient, and partially-fillable preference.	The user’s target-price constraint and LIMIT order type. Do not convert a limit order into an immediate swap unless the user confirms.
Sell TWAP	Source token, destination token, total source amount to sell, slice count, cadence/interval, deadline/expiry, recipient, slippage/price constraints.	The total source amount and TWAPOrder family. Split source amount across slices.
Buy TWAP	Source token, destination token, total destination amount to receive, max source spend, slice count, cadence/interval, deadline/expiry, recipient, slippage/price constraints.	The total destination target and TWAPBuyOrder family. Split destination target across slices and cap source spend.
OTC / AugustusRFQ	Counterparty, token pair, amount, price, expiry, fill permissions.	OTC/RFQ settlement semantics. Do not label it as a standard limit order.

Delta advanced orders → API path

Advanced order	API path	Agent rule
Limit order	GET /v2/delta/prices → POST /v2/delta/orders/build → user signs toSign → POST /v2/delta/orders with type=LIMIT.	Pass route and toSign.value verbatim. Use limitAmount when the target-price constraint needs an explicit amount override.
Sell TWAP	GET /v2/delta/prices for one source slice → POST /v2/delta/orders/build with orderType=TWAPOrder, interval, numSlices, and totalSrcAmount.	Preserve total source amount and split source across slices. route.origin.input.amount must equal floor(totalSrcAmount / numSlices).
Buy TWAP	GET /v2/delta/prices for one destination slice → POST /v2/delta/orders/build with orderType=TWAPBuyOrder, interval, numSlices, totalDestAmount, and maxSrcAmount.	Preserve total destination amount, split destination across slices, and cap source spend. route.origin.output.amount must equal floor(totalDestAmount / numSlices).
Read status	GET /v2/delta/orders/{orderId}, GET /v2/delta/orders/hash/{hash}, or paginated GET /v2/delta/orders.	Narrow on type and onChainOrderType: LIMIT, TWAPOrder, TWAPBuyOrder, FillableOrder, etc.

Missing information → ask or proceed

Situation	Agent decision	Prompt to user
Token, chain, amount, and direction are all clear	Proceed to quote.	None.
Token symbol exists on multiple chains	Ask for the chain.	”Which chain should I use for USDC?”
Token symbol maps to multiple token contracts on the same chain	Ask for the token address or show choices.	”I found multiple tokens named X. Which contract should I use?”
Slippage is missing	Use the app’s configured default, or ask if no default exists.	”What slippage tolerance should I use?”
User asks for maximum balance swap	Ask for confirmation before quoting the full balance.	”Do you want to swap your entire balance, excluding gas if needed?”
Price impact is high	Warn and ask for confirmation before signing.	”This route has high price impact. Do you want to continue?”
User asks for an unsupported chain	Stop and show supported alternatives.	”Velora does not support that chain for this flow yet. Choose one of these chains instead.”

Error or symptom → recovery action

Symptom	Likely cause	Agent recovery
400 for missing slippage	Quote request is incomplete.	Add slippage in basis points and retry.
Pricing error or no route	No route for the requested pair, size, chain, or mode.	Retry with mode=ALL, reduce size, change token, or ask the user for another route.
HMAC or quote validation error	The quote payload is stale or mismatched.	Requote and rebuild from the same fresh response.
Approval transaction succeeds but swap still fails allowance check	Approval went to the wrong spender or wrong chain.	Check the spender for the selected mode and ask for a new approval if needed.
User rejects transaction or signature	User declined the action.	Stop. Do not retry automatically.
Delta order remains pending	The auction or protocol settlement is still in progress, or the order may expire.	Poll status with backoff and show the latest order state. Do not resubmit blindly.
Transaction reverts	Market transaction failed on-chain.	Surface the revert, suggest requoting, and avoid replaying the same calldata.

Guardrails for agents

• Never invent token addresses, chain IDs, quotes, transaction hashes, or order IDs.
• Always set partner to the integrator’s app or project partner key. Treat my-app-name as a placeholder, not a literal value.
• Branch on the response shape: delta means Delta order flow; market means Market transaction flow.
• Keep the delta block and its hmac together. Treat them as an opaque pair.
• Requote after expiration, HMAC errors, material balance changes, or route failures.
• Ask before changing execution mode, recipient, chain, or spend direction.
• Ask for user confirmation before submitting a signed order or sending an on-chain transaction.

Trading modes

Choose between mode=DELTA, mode=MARKET, and mode=ALL.

Delta quote

Quote Delta and Market paths from the same endpoint.

Market transaction

Build calldata from a Market response.

Chains and contracts

Check supported chains and canonical contract addresses.

Limit orders

Route target-price orders to Delta order flows.

TWAP

Preserve sell-vs-buy amount semantics when splitting trades over time.