​
简介

发送到 /route 和 /msgs_direct 端点的请求中的 allow_unsafe 参数，旨在保护用户免受不良交易执行的影响。 该参数表示：当我们的路由引擎预测执行质量较低或无法确定时，你是否仍希望 API 返回并执行一条路由：
  • allow_unsafe=false（默认）：当路由引擎预测执行质量较差（即 price_impact 超过 10%，或输入与输出的 USD 价值差异超过 10%），或者无法判断执行质量时，API 会直接抛出错误，而不是返回路由。
  • allow_unsafe=true：即使路由引擎预测执行质量较差（即 price_impact 超过 10%，或输入与输出的 USD 价值差异超过 10%），或者无法判断执行质量，API 仍会为该交易返回一条路由。在这些情况下，API 会在响应中追加一个 warning 字段。
请先确认你已经理解执行质量 / 报价质量的衡量方式在阅读本文档之前，你应先阅读我们的报价质量文档：了解报价质量指标。该文档提供了基础背景，说明 Skip Go API 如何判断一条路由是否可能给用户带来较差的执行价格，主要包括输入与输出的 USD 价值差异，以及链上价格影响。

​
allow_unsafe=false 的行为

当 allow_unsafe=false 时，如果执行质量较差（通过价格影响或预估损失的 USD 价值衡量），或者无法判断执行质量（即这两项指标都不可用），端点会抛出错误。 具体来说，当 allow_unsafe=false 时，如果出现以下情况，/route 和 /msgs_direct 会返回错误：
  • price_impact > .10（该交换会使链上价格移动超过 10%）
  • (usd_amount_in-usd_amount_out)/usd_amount_in)>.10（输入价值中损失超过 10%）
  • 上述两个指标都无法计算
下面我们分别给出这几种情况下的响应示例。 价格影响超过 10%（BAD_PRICE_ERROR）： 
  "code": 3,
  "message": "swap execution price in route deviates too far from market price. expected price impact: 98.6915%",
  "details": [
    {
      "@type": "type.googleapis.com/google.rpc.ErrorInfo",
      "reason": "BAD_PRICE_ERROR",
      "domain": "skip.build",
      "metadata": {}
    }
  ]
}
用户损失的 USD 价值超过 10%（BAD_PRICE_ERROR）： 
  "code": 3,
  "message": "difference in usd value of route input and output is too large. input usd value: 1000 output usd value: 600",
  "details": [
    {
      "@type": "type.googleapis.com/google.rpc.ErrorInfo",
      "reason": "BAD_PRICE_ERROR",
      "domain": "skip.build",
      "metadata": {}
    }
  ]
}
无法计算 price_impact 与预估 USD 价值差异（LOW_INFO_ERROR）
JSON
{
  "code": 3,
  "message": "unable to determine route safety",
  "details": [
    {
      "@type": "type.googleapis.com/google.rpc.ErrorInfo",
      "reason": "LOW_INFO_ERROR",
      "domain": "skip.build",
      "metadata": {}
    }
  ]
}

​
allow_unsafe=true 的行为

当 allow_unsafe=true 时，即使路由引擎预测执行质量未知或较差（通过 price_impact 或预估 USD 损失衡量），端点仍会返回路由，但会附带一个 warning 字段。 warning 字段出现的条件，与 allow_unsafe=false 时端点会返回错误的条件完全一致，也就是：
  • price_impact > .10（该交换会使链上价格移动超过 10%）
  • (usd_amount_in-usd_amount_out)/usd_amount_in)>.10（输入价值中损失超过 10%）
  • 上述两个指标都无法计算
下面我们分别给出这几种情况下的响应示例。 价格影响超过 10%（BAD_PRICE_WARNING）：
JSON
"warning": {
    "type": "BAD_PRICE_WARNING",
    "message": "swap execution price in route deviates too far from market price. expected price impact: 98.6826%"
}
交换中损失的输入 USD 价值超过 10%（BAD_PRICE_WARNING）：
{
    "type": "BAD_PRICE_WARNING",
    "message": "difference in usd value of route input and output is too large. input usd value: 1000 output usd value: 600"
}
无法计算 price_impact 与预估 USD 价值差异（LOW_INFO_ERROR） 
"warning": {
    "type": "LOW_INFO_WARNING",
    "message": "unable to determine route safety"
}

​
保护用户的最佳实践

首先，我们建议将 allow_unsafe=false 作为默认设置。 此外，我们建议阅读我们关于安全 API 集成的文档，了解更多 UX/UI 实践，以进一步帮助防止用户执行那些事后立刻后悔的交易。
有问题或反馈？欢迎帮助我们持续改进！加入我们的 Discord，并选择 “Skip Go Developer” 角色，分享你的问题和反馈。

​
Introduction

Theallow_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 field
Make sure you understand execution/quote quality measurements firstBefore reading this doc, you should read our documentation on quote quality: Understanding Quote Quality Metrics. This provides basic background information about the different ways the Skip Go API measures whether a route will likely give a user a bad execution price, namely the difference between the USD value of the input and the output & on-chain price impact.

​
allow_unsafe=false Behavior

When allow_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)
  • Neither of the above metrics can be computed
Below, we provide examples of the responses in each these cases. The price impact is greater than 10% (BAD_PRICE_ERROR): 
  "code": 3,
  "message": "swap execution price in route deviates too far from market price. expected price impact: 98.6915%",
  "details": [
    {
      "@type": "type.googleapis.com/google.rpc.ErrorInfo",
      "reason": "BAD_PRICE_ERROR",
      "domain": "skip.build",
      "metadata": {}
    }
  ]
}
The user loses more than 10% of their USD value (BAD_PRICE_ERROR): 
  "code": 3,
  "message": "difference in usd value of route input and output is too large. input usd value: 1000 output usd value: 600",
  "details": [
    {
      "@type": "type.googleapis.com/google.rpc.ErrorInfo",
      "reason": "BAD_PRICE_ERROR",
      "domain": "skip.build",
      "metadata": {}
    }
  ]
}
The price_impact and the estimated USD value difference cannot be calculated (LOW_INFO_ERROR)
JSON
{
  "code": 3,
  "message": "unable to determine route safety",
  "details": [
    {
      "@type": "type.googleapis.com/google.rpc.ErrorInfo",
      "reason": "LOW_INFO_ERROR",
      "domain": "skip.build",
      "metadata": {}
    }
  ]
}

​
allow_unsafe=true Behavior

When allow_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)
  • Neither of the above metrics can be computed
Below, we provide examples of the responses in each these cases. The price impact is greater than 10% (BAD_PRICE_WARNING):
JSON
"warning": {
    "type": "BAD_PRICE_WARNING",
    "message": "swap execution price in route deviates too far from market price. expected price impact: 98.6826%"
}
More than 10% of the USD value of the input is lost in the swap (BAD_PRICE_WARNING):
{
    "type": "BAD_PRICE_WARNING",
    "message": "difference in usd value of route input and output is too large. input usd value: 1000 output usd value: 600"
}
The price_impact and the estimated USD value difference cannot be calculated (LOW_INFO_ERROR) 
"warning": {
    "type": "LOW_INFO_WARNING",
    "message": "unable to determine route safety"
}

​
Best Practices for Protecting Users

Above all else, we recommend setting 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.
Have questions or feedback? Help us get better!Join our Discord and select the “Skip Go Developer” role to share your questions and feedback.