Velora
Velora is a limit-order lifecycle for status checks and cancellation
Velora is a signed limit-order lifecycle in which an ERC-20 maker authorizes terms off-chain, then watches the managed order record before cancelling or replacing any remaining amount. The order hash identifies the instruction, state reports its lifecycle stage, and fillableBalance reveals what remains after fills. Cancellation targets that hash through AugustusRFQ and requires an on-chain transaction; replacement creates a separately signed order with fresh terms.
Choosing whether to leave, cancel, or replace an order
The correct Velora action follows three fields: state shows lifecycle position, fillableBalance shows the unfilled quantity, and swappableBalance shows what the system can execute now.
An EIP-712 signature does not reserve tokens. The 20-byte maker address still controls the ERC-20 balance, so transfers and allowance changes alter what AugustusRFQ can execute. Save the 32-byte order hash immediately after submission and query the maker record on the correct chain. If state is PENDING and fillableBalance equals makerAmount, no fill appears in the record. A smaller positive fillableBalance means part of the offered amount has executed. A zero swappableBalance means the remaining instruction lacks executable inventory or allowance at that moment. Together, these values determine whether waiting preserves the intended order or replacement should begin.
Record the chain ID beside the hash. That pairing identifies the exact order to review before cancellation.
Signature, approval, and cancellation costs
A Velora order signature costs no network gas, while ERC-20 approval and AugustusRFQ cancellation require on-chain transactions when those actions are needed by the maker address.
EIP-712 turns maker, assets, amounts, expiry, and nonceAndMeta into typed data that the wallet signs. Submitting that object to the managed service does not move tokens or consume a network transaction.
An approval grants AugustusRFQ spending capacity, while cancellation writes the order hash into contract state. The signature stage therefore represents zero on-chain transactions. Approval and cancellation costs follow the chain gas market, with gas used, network gas price, and native-token value setting the final amount.
An expiry value of 0 removes time-based expiration, so the instruction stays open until fillability changes, fulfillment completes, or cancellation settles. Check the cancellation receipt before posting new terms that duplicate the same exposure.
What does each Velora order status mean?
Velora exposes four lifecycle states for managed orders: PENDING remains usable, FULFILLED is fully executed, EXPIRED passed its deadline, and CANCELLED records cancellation in the service record.
A partial fill normally leaves state at PENDING while fillableBalance drops below makerAmount. Read state and remaining quantity together.
Seven managed API operations cover the lifecycle without changing the meaning of those states.
| API operation | Lifecycle use | Supported scope |
|---|---|---|
| Create order | Submit signed terms | Managed ERC-20 LIMIT orders |
| Get orders by maker | Read owner records | ERC-20 maker addresses |
| Get orders by taker | Read counterparty records | ERC-20 taker addresses |
| Get pairs | Inspect available pairs | ERC-20 pair metadata |
| Get orderbook | Inspect executable listings | ERC-20 orderbook entries |
| Fill order | Execute signed terms | Fillable ERC-20 orders |
| Cancel order | Close remaining quantity | Unfilled ERC-20 balance |
The maker query is the normal portfolio view because it returns records owned by one address, including state, orderHash, transactionHash, makerAmount, fillableBalance, swappableBalance, and makerBalance. The taker query answers a different integration need. Pair and orderbook reads reveal available market context, while create, fill, and cancel move the record through its lifecycle. A transactionHash starts as null on a new record and becomes useful after on-chain activity updates the record. Use orderHash as the stable lookup key because a replacement has its own identity and starts a separate record.
Reading fillable, swappable, and maker balances
The three Velora balance fields answer separate questions: fillableBalance tracks remaining order quantity, swappableBalance tracks immediate executability, and makerBalance reflects available maker inventory for that asset.
The remaining amount
makerAmount records the original offered quantity, while fillableBalance records the unfilled portion. The condition 0 < fillableBalance < makerAmount
identifies a partial fill. Subtracting fillableBalance from makerAmount yields the quantity already filled.
Availability at execution time
Balance fields use raw token units. Ethereum USDC uses 6 decimals, while DAI uses 18, so applications must format each integer with its own ERC-20 decimal value. A decimal mismatch changes the displayed quantity by powers of ten even though the integer record itself remains unchanged.
Maker balance
makerBalance caps what the address can provide from its wallet balance. A transfer out of the wallet reduces that capacity without rewriting the signed amounts, which explains why PENDING and full executability can diverge.
Swappable balance
swappableBalance is the amount that the system can fill at the time of the status check. It incorporates the practical constraints represented by the remaining order, maker inventory, and allowance. When fillableBalance stays positive but swappableBalance reaches 0, the order record still preserves its terms, yet immediate execution has no available quantity. Restore the required inventory and approval if the terms remain suitable; otherwise, move to cancellation.
The cancellation and replacement sequence
Replacing a Velora order uses two distinct identities: cancel the surviving balance under the old order hash, then sign and submit fresh terms under another hash.
Retrieve the latest maker record first and confirm its chain ID, state, fillableBalance, and swappableBalance. If state remains PENDING, submit the old order hash to the AugustusRFQ cancellation action from the maker wallet. Keep tracking that hash until the record shows CANCELLED or FULFILLED, because an execution can change the remaining amount while the cancellation transaction awaits confirmation. Then choose new makerAmount, takerAmount, and expiry values, build a fresh EIP-712 object, sign it, and submit it as another managed order.
For managed orders, nonceAndMeta combines the taker address with a random integer from 0 through 2^53–1 shifted left by 160 bits. Fresh nonce data and revised terms produce a separate order hash, so the replacement does not edit the earlier signed payload. The new hash becomes the object for every later status check.
When should a partially filled order be cancelled?
A partially filled Velora order should be cancelled when its remaining ratio no longer matches the intended position, its expiry is unsuitable, or immediate executability has disappeared.
The arithmetic is direct: 0 < fillableBalance < makerAmount
proves that execution has consumed only part of the maker quantity. The filled share equals 1 - fillableBalance / makerAmount, using raw units from the same token. A maker query also offers hideSmallBalances, which defaults to false; when enabled, it hides records after 99.99% of their value has already been swapped. That display filter does not alter state or cancel the residue.
A market chart touching the limit price does not create a fill by itself. A taker still needs an executable, worthwhile route while that price exists. Velora Delta broadens access to multiple execution agents, yet a brief price touch or an uneconomic route can leave the record PENDING. Base the adjustment on state, fillableBalance, and swappableBalance rather than the chart candle alone, then cancel the exact remaining instruction if its ratio no longer fits.
Expiry, chain scope, and advanced edge cases
Reliable Velora lifecycle checks require the query, wallet, token allowance, and cancellation transaction to reference the same AugustusRFQ deployment and chain ID for consistent interpretation.
AugustusRFQ support covers six chains: Ethereum, Arbitrum, Avalanche, BNB Smart Chain, Optimism, and Polygon. Their chain IDs are 1, 42161, 43114, 56, 10, and 137, respectively. The wider order structure also encodes three token standards: ERC-20, ERC-721, and ERC-1155. The fungible operations on this page concern ERC-20 records, whose makerAsset and takerAsset fields each identify a token contract on one selected chain.
Expiry uses a timestamp in seconds, while the value 0 means that time alone never closes the order. For API clients, a maximum polling rate of 1 request per second avoids excessive status calls. Maker queries support pagination through limit and offset, and hideSmallBalances defaults to false. After any allowance change, transfer, fill, or cancellation submission, fetch the record again rather than carrying forward an earlier swappableBalance. The newest response determines whether the next action targets a live remainder, a completed order, or a cancelled hash.
The next action should follow the newest record on the recorded chain, not a cached interface label.
Velora - common questions
Can closing the Velora interface cancel a pending limit order?
Closing the interface does not cancel a pending Velora limit order. The signed instruction remains available until AugustusRFQ records fulfillment or cancellation, or the expiry timestamp passes. Reopen the maker view on the same chain, locate the order by its hash, and inspect state plus fillableBalance. A deliberate cancellation still requires the wallet to submit an on-chain transaction for the old hash.
Does reducing ERC-20 allowance automatically mark an order as CANCELLED?
Reducing ERC-20 allowance does not change a Velora order to CANCELLED by itself. The managed record can continue to show PENDING while swappableBalance falls because AugustusRFQ lacks enough spending capacity. makerBalance and fillableBalance answer different questions, so neither substitutes for the allowance check. Restore sufficient approval if the terms remain wanted, or submit cancellation and wait for its record before creating replacement terms. The state changes only through fulfillment, expiration, or a completed cancellation action.
What happens if a Velora order uses an expiry of 0?
An expiry of 0 creates a Velora order without time-based expiration. The order remains eligible while its state is PENDING, its remaining balance is positive, and token balance and allowance support execution. Because no timestamp will close it, the maker must monitor the hash until it becomes FULFILLED or CANCELLED. Moving funds alone does not create a cancellation record.
Can the same token balance support two pending Velora orders?
Two Velora orders can reference the same ERC-20 wallet balance because signing does not escrow or reserve tokens. Their combined requested maker amounts can exceed the inventory that remains executable, even while both records show PENDING. swappableBalance provides the immediate view for each record after balance and allowance constraints. Cancelling one order frees no separate vault balance; it removes that signed instruction from future execution after settlement. Review both records again after every transfer or fill.
Why is transactionHash null on a newly submitted order?
A null transactionHash is normal before a Velora limit order has related on-chain execution data. Creation submits signed EIP-712 terms to the managed service, so no swap transaction exists at that stage. Track the order through orderHash, state, and the three balance fields. Once on-chain activity updates the record, transactionHash becomes useful for examining that transaction on the selected network.
Do I need a fresh token approval after replacing an order?
A fresh approval is unnecessary when the existing ERC-20 allowance to the applicable AugustusRFQ deployment covers the new maker amount. Replacement changes the signed terms and order hash, but it does not automatically erase an allowance granted for the same token and contract. A token change, contract-version change, reduced allowance, or larger maker amount requires another approval transaction before swappableBalance can reflect the full replacement quantity. Read the allowance on the replacement chain before relying on its status.
Are maker and taker queries interchangeable for a restricted order?
Maker and taker queries serve different address roles in Velora order tracking. The maker query returns orders created by that owner, while the taker query returns orders assigned to the specified taker address. Public LIMIT records and address-restricted P2P records also use separate order types in the managed API. Preserve chain ID, type, and orderHash together so each status check reaches the intended record.