set_fx_rate_override · Override an FX rate

Contract

shape: entity
authority: act
evidence: none
subscription: false
permission: any one of: account.finance (admits nobody until an account finance role in tradehq_identity.account_member); staff.finance (the staff role staff_finance held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first
idempotency: keyed
emits: fx.overridden
MCP tool: set_fx_rate_override
decision_set: approve, reject, edit, request_info
REST: POST https://api.containertradehq.com/v1/cap/set_fx_rate_override

Through MCP this call returns an approval request first; see Approvals.

Idempotency: keyed by the caller's Idempotency-Key, which is required: the same key and inputs replay the first result, the same key with other inputs is 409 idempotency_key_reused

Inputs

name	type	required	validation
currency	currency	required	iso4217 The currency whose EUR rate is overridden: an ISO 4217 code, not EUR.
rate_date	date	required	date, YYYY-MM-DD The day the override is for, YYYY-MM-DD. Not in the future.
rate	positive_decimal	required	positive-decimal Units of the currency per one EUR, as a string of digits.
reason	text	required	1 to 500 characters Why the fetched rate is not the one to use. Kept with the override.
account_id	account_id	optional	tradehq-account-id The account it applies to. Absent: every account (staff.finance only).

Response

fx_rate_override_id · string · The override's id.
account_id · stringnull · The account it applies to; null for every account.
rate_date · string · The day it is for.
base_currency · string · Always EUR.
currency · string · The currency overridden.
rate · value · The override's rate.
fetched_rate · stringnull · ECB's rate for the same currency and day, kept; null when ECB published none.
reason · string · Why.
set_by · string · Who set it.
set_at · string · When.

Full JSON Schema

{
  "type": "object",
  "properties": {
    "fx_rate_override_id": {
      "type": "string",
      "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$",
      "format": "uuid",
      "description": "The override's id.",
      "x-data-class": "operational"
    },
    "account_id": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
      "format": "tradehq-account-id",
      "description": "The account it applies to; null for every account.",
      "x-data-class": "operational"
    },
    "rate_date": {
      "type": "string",
      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$",
      "format": "date",
      "description": "The day it is for.",
      "x-data-class": "operational"
    },
    "base_currency": {
      "type": "string",
      "pattern": "^[A-Z]{3}$",
      "format": "iso4217",
      "description": "Always EUR.",
      "x-data-class": "operational"
    },
    "currency": {
      "type": "string",
      "pattern": "^[A-Z]{3}$",
      "format": "iso4217",
      "description": "The currency overridden.",
      "x-data-class": "operational"
    },
    "rate": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^[0-9]+(\\.[0-9]+)?$",
          "format": "positive-decimal"
        },
        {
          "const": "•••",
          "description": "Masked by the caller's data policy."
        },
        {
          "type": "null",
          "description": "Denied by the caller's data policy."
        }
      ],
      "description": "The override's rate.",
      "x-data-class": "commercial"
    },
    "fetched_rate": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^[0-9]+(\\.[0-9]+)?$",
      "format": "positive-decimal",
      "description": "ECB's rate for the same currency and day, kept; null when ECB published none.",
      "x-data-class": "operational"
    },
    "reason": {
      "type": "string",
      "description": "Why.",
      "x-data-class": "operational"
    },
    "set_by": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-user-id",
      "description": "Who set it.",
      "x-data-class": "operational"
    },
    "set_at": {
      "type": "string",
      "format": "date-time",
      "description": "When.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "fx_rate_override_id",
    "account_id",
    "rate_date",
    "base_currency",
    "currency",
    "rate",
    "fetched_rate",
    "reason",
    "set_by",
    "set_at"
  ],
  "additionalProperties": false
}

Refusals

not yet declared

The platform refusals apply to every call: version, authentication, authority, validation and rate limits, each in the same envelope.

Surfaces

DesktopF

MobileF

APIF

MCPF*

VoiceD2

PushF

OneBoxN

OutboundN

MCP: approval required
Voice: degraded: confirmation
OneBox: no document originates an FX override
Outbound: crosses to no counterparty

Events

fx.overridden audit_only

None.