allow_unsafe
parameter in the requests to /route
& /msgs_direct
endpoints is designed to protect users from bad trade execution.
This parameter indicates whether you want to allow the API to return and execute a route even when our routing engine forecasts low or unknown execution quality:
allow_unsafe=false
(default): The API will throw an error instead of returning a route when the routing engine forecasts bad execution quality (i.e. > 10% price_impact
or difference between USD value in and out) or when execution quality can’t be determined.allow_unsafe=true
: The API will return a route for a trade even when the routing engine forecasts bad execution quality (i.e. > 10% price_impact
or difference between USD value in and out) or when execution quality can’t be determined. In these cases, the API appends a warning
to the response in a warning
fieldallow_unsafe=false
Behaviorallow_unsafe=false
, the endpoint throws an error when execution quality is poor (as measured by price impact or estimated USD value lost) or when execution quality can’t be determined (i.e. neither of these measurements are available).
In particular, if allow_unsafe=false
, /route
and /msgs_direct
return errors when:
price_impact > .10
(the swap will move the on-chain price by more than 10%)(usd_amount_in-usd_amount_out)/usd_amount_in)>.10
(greater than 10% of the value of the input is lost)BAD_PRICE_ERROR
):
BAD_PRICE_ERROR
):
price_impact
and the estimated USD value difference cannot be calculated (LOW_INFO_ERROR
)
allow_unsafe=true
Behaviorallow_unsafe=true
, the endpoints will still return routes even when the routing engine forecasts will have unknown or poor execution quality (measured by price_impact or estimated USD lost), but they will have a warning
field appended to them.
The warning
field is populated exactly when the endpoints would return an error if allow_unsafe
were false
, namely:
price_impact > .10
(the swap will move the on-chain price by more than 10%)(usd_amount_in-usd_amount_out)/usd_amount_in)>.10
(greater than 10% of the value of the input is lost)BAD_PRICE_WARNING
):
BAD_PRICE_WARNING
):
price_impact
and the estimated USD value difference cannot be calculated (LOW_INFO_ERROR
)
allow_unsafe=false
In addition, we recommend reading our documentation around safe API integrations to learn about UX/UI practices that can further help prevent users from performing trades they’ll immediately regret.