Cobre 的 FX Rate Alerts API 提供实时通知机制，使客户能够监控外汇汇率走势，并在市场条件满足预设阈值时即时收到警报。

该功能赋能财资和财务团队，通过自动化跨多个货币对的 FX 汇率监控，捕捉有利的市场机会、主动管理货币风险，并 优化跨境支付时机。

FX Rate Alerts 遵循清晰的生命周期，由 可配置条件、实时监控 和 Webhook 通知 驱动，确保客户不会错过任何关键的市场动态。

创建 FX Rate Alerts

客户通过定义特定货币对的监控条件来创建 FX Rate Alerts。警报激活后，Cobre 平台将持续监控实时 FX 汇率，并在条件满足时触发通知。

支持的警报条件：

Above：当 FX 汇率超过最大阈值时触发

Below：当 FX 汇率跌破最小阈值时触发

Within Range：当 FX 汇率进入指定区间时触发

要接收警报通知，客户须订阅以下事件：

alerts.fx_rate.triggered —— 警报条件满足时的通知

订阅后，每次警报被触发时，客户都将收到一条 Webhook。

FX Rate Alerts 生命周期

创建
客户通过 POST /v1/alerts 提交包含条件参数和到期日期的请求，创建警报。

主动监控
Cobre 对所有处于激活状态（active_status: true）的警报实时监控 FX 汇率。

触发事件
当市场汇率满足警报条件时，系统将发送包含触发时 FX 汇率的 Webhook。

停用
客户可通过 DELETE /v1/alerts/{id} 停用警报，系统将把 active_status 设置为 false。

已停用的警报仍保留在系统中以供审计，但不会再触发通知。警报也会根据其 valid_until 日期自动过期。

警报触发通知

当客户订阅 alerts.fx_rate.triggered 后，将通过 Notifications API 接收警报通知。更多信息请参阅：通知与订阅

警报元数据

metadata 对象包含警报配置信息，以及在适用时触发该警报的 FX 汇率。

元数据字段

字段	说明
`currency_pair`	被监控的货币对（例如 `usd/cop`、`usd/mxn`）
`condition`	警报条件类型：`above`、`below` 或 `within_range`
`max_rate`	最大汇率阈值（用于 `above` 和 `within_range` 条件）
`min_rate`	最小汇率阈值（用于 `below` 和 `within_range` 条件）
`fx_rate`	触发警报的实际 FX 汇率（仅存在于触发通知中）

fx_rate 字段仅包含在 alerts.fx_rate.triggered Webhook 载荷中，表示警报条件满足时的市场汇率。

警报条件目录

根据您的监控策略，警报可配置为以下三种条件类型。

Above Condition

Below Condition

Within Range Condition

触发逻辑： 当 current_rate > max_rate 时警报触发

适用场景： 当货币升值超过某一阈值时发送通知

必填字段：

condition："above"

max_rate：数值型阈值

示例：

{
  "metadata": {
    "condition": "above",
    "currency_pair": "usd/cop",
    "max_rate": 3500
  }
}

创建警报的请求结构

创建新的 FX Rate Alert 时，请提交以下载荷：

{
  "type": "fx_rate",
  "alias": "My Alert Name",
  "metadata": {
    "condition": "above|below|within_range",
    "currency_pair": "usd/cop",
    "max_rate": 3500,
    "min_rate": 3400
  },
  "valid_until": "2026-12-31T23:59:59Z"
}

字段说明

字段	类型	是否必填	说明
`type`	string	是	必须为 `"fx_rate"`
`alias`	string	否	警报的友好名称
`metadata.condition`	string	是	取值之一：`above`、`below`、`within_range`
`metadata.currency_pair`	string	是	需监控的货币对（例如 `usd/cop`）
`metadata.max_rate`	number	条件必填	`above` 和 `within_range` 条件时必填
`metadata.min_rate`	number	条件必填	`below` 和 `within_range` 条件时必填
`valid_until`	string	是	ISO 8601 时间戳——警报到期日期

最佳实践

警报配置

根据历史波动率和您的执行窗口设置合理的阈值

对机会性执行策略使用 within_range 条件

设置合适的 valid_until 日期，避免过期警报累积

Webhook 处理

使用 event_id 实施幂等性检查，以处理重复的 Webhook 投递

存储触发警报中的 fx_rate 值，供审计和决策使用

对 Webhook 投递失败设置监控告警

警报管理

定期审查并停用不再相关的警报

使用有描述性的 alias 值，便于团队识别各警报

监控 updated_at 字段，追踪警报最后修改时间

安全性

处理前验证所有 Webhook 签名

对 Webhook 投递使用 HTTPS 接口端点

定期轮换您的 event_signature_key

常见使用场景

Rate Lock Timing

Risk Hedging

Opportunity Window

场景： 当 USD/COP 汇率跌破 4000 时执行大额付款

配置：

{
  "type": "fx_rate",
  "alias": "Execute Payment Window",
  "metadata": {
    "condition": "below",
    "currency_pair": "usd/cop",
    "min_rate": 4000
  },
  "valid_until": "2026-06-30T23:59:59Z"
}

工作流程：

当 USD/COP < 4000 时警报触发

收到包含 fx_rate: 3985.50 的 Webhook

通过创建 FX 报价 API 自动发起汇率锁定

以锁定汇率执行跨境支付

支持的货币对

FX Rate Alerts 当前支持以下货币对：

货币对	说明
`usd/cop`	美元兑哥伦比亚比索
`cop/usd`	哥伦比亚比索兑美元
`usd/mxn`	美元兑墨西哥比索
`mxn/cop`	墨西哥比索兑哥伦比亚比索

未来可能支持更多货币对。如需自定义货币对，请联系您的 Cobre 客户代表。

错误处理

常见错误场景

HTTP 状态码	错误	解决方案
`400 Bad Request`	无效的条件类型	请使用 `above`、`below` 或 `within_range`
`400 Bad Request`	缺少必填的汇率字段	`above` 需包含 `max_rate`，`below` 需包含 `min_rate`，`within_range` 两者均需包含
`400 Bad Request`	无效的货币对	请仅使用受支持的货币对
`401 Unauthorized`	身份验证失败	请检查您的 API 凭证和授权请求头
`404 Not Found`	警报 ID 不存在	请从您的警报列表中核实警报 ID
`422 Unprocessable Entity`	无效的 `valid_until` 日期	请确保日期为未来时间且格式正确

频率限制

警报创建受账户限额约束。

FX Rate Alerts 可执行操作

➕ Create Alert

🔍 Obtain All Alerts

📄 Get One Alert

🗑️ Deactivate An Alert

说明： 创建一个具有自定义条件的新 FX 汇率监控警报。

执行后的预期结果：
生成一个新的 Alert 对象，其状态为 active_status: true，并具有唯一的警报 ID。

Webhook 通知：
已订阅 alerts.fx_rate.created 的用户将立即收到通知。

📘 了解更多： 🔗 创建警报

如何开始使用

Subscribe to alert notifications

订阅 alerts.fx_rate.triggered 事件通知。

Create your first alert

向 /v1/alerts 发送 POST 请求，并填写所需条件及货币对。

Monitor webhook deliveries

配置 Webhook 接口端点，以在 Alert 触发时接收通知。

Verify webhook signatures

使用 event_signature 请求头及订阅的 event_signature_key 对接收到的 Webhook 进行签名验证。

Take action on alerts

Alert 触发后，使用 fx_rate 值决定是否锁定汇率、执行支付或调整对冲策略。

Manage alert lifecycle

随市场行情变化，对 Alert 进行列表查询、详情获取及停用管理。

使用此 API 后的预期效果

Proactive FX risk management

无需人工监控，即可即时响应有利或不利的市场行情变动。

Optimized cross-border payment timing

通过接收实时通知，在最优汇率时机执行交易。

Reduced operational overhead

自动化货币汇率监控，无需全天手动查询汇率。

Multi-currency portfolio coverage

同时为多个货币对（USD/COP、USD/MXN、MXN/COP 等）配置 Alert 覆盖。

Audit trail and compliance

完整留存 Alert 配置及触发事件记录，满足资金管理报告与合规要求。

Integration with trading workflows

将 Alert 触发事件作为信号，通过其他 Cobre API 发起汇率锁定、报价请求或支付执行。

FX 汇率预警

创建 FX Rate Alerts#

FX Rate Alerts 生命周期#

警报触发通知#

警报元数据#

元数据字段#

警报条件目录#

创建警报的请求结构#

字段说明#

最佳实践#

警报配置#

Webhook 处理#

警报管理#

安全性#

常见使用场景#

支持的货币对#

错误处理#

常见错误场景#

频率限制#

FX Rate Alerts 可执行操作#

如何开始使用#

使用此 API 后的预期效果#

创建 FX Rate Alerts

FX Rate Alerts 生命周期

警报触发通知

警报元数据

元数据字段

警报条件目录

创建警报的请求结构

字段说明

最佳实践

警报配置

Webhook 处理

警报管理

安全性

常见使用场景

支持的货币对

错误处理

常见错误场景

频率限制

FX Rate Alerts 可执行操作

如何开始使用

使用此 API 后的预期效果