list_fx_rates · List FX rates · Container Trade HQ API

Contract

shape: collection
authority: read
evidence: none
subscription: false
permission: any one of: org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first
idempotency: safe
emits: none
MCP tool: list_fx_rates
REST: POST https://api.containertradehq.com/v1/cap/list_fx_rates

Idempotency: a read: calling again changes nothing

Inputs

name	type	required	validation
org_id	org_id	required	tradehq-org-id; 1 to 20 characters The org whose rates to list. Its account's overrides apply.
on	date	optional	date, YYYY-MM-DD The day, YYYY-MM-DD. Today in UTC when absent.
per	currency	optional	iso4217 Express every rate per one unit of this currency, e.g. the account's reporting currency. EUR when absent. Nothing is listed when it has no rate; a code ISO 4217 does not assign is refused (currency_not_iso4217).

Paginated: next next_after · ceiling not_declared

Response

items · object[]
next_after · stringnull · Pass as `after` for the next page; null on the last one.

Full JSON Schema

{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "currency": {
            "type": "string",
            "pattern": "^[A-Z]{3}$",
            "format": "iso4217",
            "description": "The currency the rate is in.",
            "x-data-class": "operational"
          },
          "per": {
            "type": "string",
            "pattern": "^[A-Z]{3}$",
            "format": "iso4217",
            "description": "One unit of this currency buys `rate` of `currency`.",
            "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 effective rate, to ten decimal places at most.",
            "x-data-class": "commercial"
          },
          "rate_date": {
            "type": "string",
            "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$",
            "format": "date",
            "description": "The day the rate is for (the older leg's, for a cross rate).",
            "x-data-class": "operational"
          },
          "source": {
            "type": "string",
            "enum": [
              "ecb",
              "override"
            ],
            "description": "ecb, or override when an override made either leg.",
            "x-data-class": "operational"
          },
          "overridden": {
            "type": "boolean",
            "description": "Whether an override made the rate.",
            "x-data-class": "operational"
          },
          "fetched_rate": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^[0-9]+(\\.[0-9]+)?$",
            "format": "positive-decimal",
            "description": "What ECB's rates alone give for the same day; null when ECB published none for a leg.",
            "x-data-class": "operational"
          }
        },
        "required": [
          "currency",
          "per",
          "rate",
          "rate_date",
          "source",
          "overridden",
          "fetched_rate"
        ],
        "additionalProperties": false
      }
    },
    "next_after": {
      "type": [
        "string",
        "null"
      ],
      "description": "Pass as `after` for the next page; null on the last one."
    }
  },
  "required": [
    "items",
    "next_after"
  ],
  "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

VoiceD4

PushN

OneBoxN

OutboundN

Voice: degraded: visualization
Push: emits nothing
OneBox: no document originates a rate listing
Outbound: crosses to no counterparty

Events

None emitted.

None.