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 汇率。

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

停用
客户可通过 DELETE /v1/alerts/{id} 停用预警，该操作将 active_status 设置为 false。

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

预警触发通知

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

预警元数据

metadata 对象包含预警配置及适用情况下的触发汇率信息。

元数据字段

字段	说明
`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 签名

使用 HTTPS 接口端点接收 Webhook 推送

定期轮换 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 时预警触发

收到 Webhook，其中 fx_rate: 3985.50

通过创建 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 的客户将立即收到通知。

📘 了解更多： 🔗 Create Alert

如何开始使用

Subscribe to alert notifications

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

Create your first alert

向 /v1/alerts 发送 POST 请求，并指定所需的触发条件和货币对。

Monitor webhook deliveries

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

Verify webhook signatures

使用 event_signature 请求头及订阅的 event_signature_key 验证传入的 Webhook 签名。

Take action on alerts

当告警触发时，使用 fx_rate 的值来决定是否锁定汇率、执行支付或调整对冲策略。

Manage alert lifecycle

随着市场条件的变化，对告警进行列表查询、详情检索及停用管理。

使用此 API 后的预期效果

Proactive FX risk management

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

Optimized cross-border payment timing

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

Reduced operational overhead

以自动化方式监控汇率，无需在一天内反复手动查询。

Multi-currency portfolio coverage

同时为多个货币对（USD/COP、USD/MXN、MXN/COP 等）设置告警。

Audit trail and compliance

完整记录告警配置及触发事件的历史，以满足资金管理报告需求。

Integration with trading workflows

将告警触发事件作为信号，通过其他 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 后的预期效果