POST https://api.trustware.io/api/v1/routes/route
Builds the full transaction payload for signing and broadcasting. Call this after the user confirms the quote. Trustware creates an intent record internally so the transaction can be tracked from receipt submission through final settlement.
The response’s intentId identifies the transaction from here on. Store it against your own record, such as a user or withdrawal ID, because /status doesn’t return the metadata you pass here.
Request
Destination calls with hooks.postHook
Passhooks.postHook to execute a contract call on the destination chain once the routed funds arrive, instead of paying the destination token to a recipient address. Destination calls are EVM only and provider dependent.
This example routes the native asset on Avalanche into a contract on Base, funding the call with the destination native asset. callData is the ABI encoding of depositNativeFor(address recipient) for the recipient in toAddress.
Requests are rejected before routing when
target or callData is missing, when fullAmount is true without amountInputPos, or when neither fundAmount nor fullAmount is supplied. A posthook the API rejects returns 400 with a message describing the problem.
hooks.postHook is also accepted on POST /api/v1/routes/deposit-address. Deposit-address routing is provider dependent, and so are deposit-address routes with a posthook, so that path is not available on every route.
The route status reflects the provider’s aggregate result. There is no separate
field reporting the destination call on its own, so verify destination state by
reading your own contract.
Response
Read token approvals before you process
route.execution.approvals: an amount of "0" is a step you must send.
Expiry
Every route comes withexpiresAt, next to intentId. /status also shows it until you commit the transaction. POST /api/v1/routes/deposit-address returns it in the same place.
Broadcast the transaction before expiresAt. After it, build a new route instead. The routing provider may revert, refund, or fill the old one at a worse price.
Judge expiresAt on Trustware’s clock, not on the device’s. Every response’s Date header gives you Trustware’s time. Compare expiresAt with the route response’s Date plus the time elapsed since you received it, rather than with the local clock. Date has one-second resolution, so err early.
Read expiresAt from each response rather than assuming a fixed window, because it depends on the route. On some Solana routes, which is provider dependent, it is at most about 60 seconds after the route is built, because that is how long the transaction’s blockhash stays valid.
If you broadcast before expiresAt but commit after it, the commit still works. See committing late.
Error responses
When no provider can build the route, the endpoint returns a judged result rather than one opaque message. A top-levelcode gives the verdict for the request as a whole, and providers carries one entry per provider consulted saying why it is out.
A provider missing from
providers was not consulted, so absence is not a decline.
Decline codes
Returned withoutcome: "declined". The provider answered and said no, which is a negative result rather than a fault.
Failure codes
Returned withoutcome: "failed". The provider did not produce a usable answer.
Because these are faults rather than refusals, a response containing one arrives as
503, and the pair may still be routable on a later attempt.
From
@trustware/sdk 1.1.15 the SDK throws this as a RouteError carrying
status, code, and providers. Through 1.1.13 it throws a plain Error
carrying only the error summary. See the RouteError
class.Token approvals
If the source token is an ERC-20, the required allowances must be granted before the route transaction is broadcast. The spender is always a provider contract, never a Trustware contract. Whenroute.execution.approvals is present, each entry is the authoritative source for one allowance: approve amount of tokenAddress for spender on chainId. Grant each one, wait for it to confirm, then broadcast route.execution.transaction.
Process the entries in order. Skip an entry that has no tokenAddress or no spender.
An entry can have an amount of "0". Whether a route includes one is provider dependent. It is a reset-to-zero step, not an empty entry: some tokens refuse to change a non-zero allowance to another non-zero value, so the old allowance has to be cleared first. Send it unless the current allowance is already zero. Skipping it makes the next approval revert.
Every provider sets amount. An entry with no amount, or one that is not a whole number, is a broken response. Don’t send that route.
An ERC-20 source route returns them inside route.execution:
approvals rather than reusing an earlier response. You can also check a specific allowance with GET /allowance before broadcasting.
This is a source-chain allowance and is unrelated to hooks.postHook.toApprovalAddress, which controls a destination-chain allowance for a destination contract call.
The @trustware/sdk headless core handles the source allowances automatically on EVM routes: Trustware.sendRouteTransaction() reads the current allowance, submits an approval for the exact amount when one is missing, waits for confirmation, and then sends the route transaction.