Skip to main content

Integrating Aqueducta

Aqueducta is intended for wallets, apps, and routing-aware integrations on Movement.

For most user-facing flows:

  1. call POST /v1/quote with routing_mode=fast
  2. render the best route immediately
  3. optionally call POST /v1/routes with routing_mode=balanced
  4. show alternate routes once they arrive

That is the same pattern used by the Route Preview page in this docs site.

What to Persist Client-Side​

If you cache responses client-side, key them by:

  • snapshot_id
  • token_in
  • token_out
  • amount_in
  • slippage_bps
  • max_hops
  • routing_mode

When snapshot_id changes, invalidate cached quote data.

What to Read From the Response​

The most important fields for integrators are:

  • snapshot_id
  • quote_id
  • route_id
  • quality
  • route
  • routes
  • diagnostics
  • required_snapshot_id support for replayable quote verification
  • partner_fee_bps / partner_fee_recipient for explicit integrator fees

If execution hints are enabled, the response may also include:

  • execution.module
  • execution.function
  • execution.route_hash
  • execution.bcs_payload_hex

The intended public execution target is router_v3, which adds:

  • explicit recipient settlement
  • explicit output-side partner fee settlement
  • stable versioned route hashing

Error Handling​

Treat these as expected product cases:

  • NO_ROUTE
    • no valid path was found
  • NO_QUOTE
    • a path existed but none of the candidates were quotable
  • SNAPSHOT_UNAVAILABLE
    • the router is not ready yet
  • INVALID_TOKEN
    • invalid token identifier format

Do not silently collapse these into a generic failure in the UI.

Operational Signals​

Operators and advanced integrators should watch:

  • GET /v1/status
    • snapshot age
    • discovery coverage
    • route-candidate cache state

Current Integration Boundaries​

Aqueducta currently assumes:

  • exact-in swaps
  • single-route execution
  • Movement L1 assets and pools

Current fee model:

  • default fee is zero
  • optional integrator fees are output-side, explicit, and reflected in net quote output

If your integration requires split routing or exact-out semantics, that is future scope, not current API behavior.