Currency conversion at ECB rates, for AI agents

What it does

Uses the euro foreign exchange reference rates of the European Central Bank (ECB), published around 16:00 CET on every TARGET business day since 4 January 1999. Give an amount, a source currency, one or more target currencies (or none, for all of them) and optionally a date. On a weekend or holiday the last rate published before that date is used, and the rate date is returned. Rates between two non-euro currencies are crossed through the euro. Amounts and rates are decimal strings computed exactly, rounded half away from zero to the currency's minor unit (0 decimals for JPY, ISK, KRW; 2 for the others) unless decimals is given. Reference rates are for information: banks and card networks apply their own rates and fees.

What it is for

Use it from your code

From Claude, once connected

> Convert 1,250 USD to EUR and GBP at the ECB rate of 15 March 2024.

curl

curl https://api.useholon.com/v0/calls \
  -H "Authorization: Bearer $HOLON_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent": "holon-labs/currency-convert", "input": {"amount": "1250", "from": "USD", "to": ["EUR", "GBP"], "date": "2024-03-15"}}'

Python

import os, requests

r = requests.post("https://api.useholon.com/v0/calls",
    headers={"Authorization": f"Bearer {os.environ['HOLON_AGENT_KEY']}"},
    json={"agent": "holon-labs/currency-convert",
          "input": {"amount": "1250", "from": "USD", "to": ["EUR", "GBP"]}})
out = r.json()["output"]
for c in out["conversions"]:
    print(c["currency"], c["amount"], "at", c["rate"], "on", out["rate_date"])

JavaScript

const r = await fetch("https://api.useholon.com/v0/calls", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.HOLON_AGENT_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ agent: "holon-labs/currency-convert", input: { amount: "99.90", from: "EUR", to: "JPY" } }),
});
const { output } = await r.json();
console.log(output.conversions[0].amount, output.rate_date);

Call it

claude mcp add --transport http holon https://api.useholon.com/mcp --header "Authorization: Bearer <agent key>"

curl https://api.useholon.com/v0/calls \
  -H "Authorization: Bearer <agent key>" \
  -H "Idempotency-Key: <any unique id>" \
  -d '{"agent":"holon-labs/currency-convert","input":{"amount":"1250.00","from":"USD","to":["EUR","GBP"]}}'

Interface

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "from"
  ],
  "properties": {
    "amount": {
      "type": [
        "string",
        "number"
      ],
      "default": "1",
      "description": "A decimal, such as \"1234.56\""
    },
    "from": {
      "type": "string",
      "pattern": "^[A-Za-z]{3}$",
      "description": "ISO 4217 code, such as USD"
    },
    "to": {
      "description": "One code or a list; omit for every currency quoted that day",
      "oneOf": [
        {
          "type": "string",
          "pattern": "^[A-Za-z]{3}$"
        },
        {
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^[A-Za-z]{3}$"
          },
          "minItems": 1,
          "maxItems": 40
        }
      ]
    },
    "date": {
      "type": "string",
      "format": "date",
      "description": "Rate of this day (YYYY-MM-DD); omit for the latest"
    },
    "decimals": {
      "type": "integer",
      "minimum": 0,
      "maximum": 10
    }
  }
}

{
  "type": "object",
  "required": [
    "amount",
    "from",
    "rate_date",
    "conversions",
    "source"
  ],
  "properties": {
    "amount": {
      "type": "string"
    },
    "from": {
      "type": "string"
    },
    "date_requested": {
      "type": [
        "string",
        "null"
      ]
    },
    "rate_date": {
      "type": "string"
    },
    "conversions": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "currency",
          "rate",
          "amount"
        ],
        "properties": {
          "currency": {
            "type": "string"
          },
          "rate": {
            "type": "string"
          },
          "amount": {
            "type": "string"
          }
        }
      }
    },
    "source": {
      "type": "object"
    }
  }
}

Declared errors

Example: Dollars to euros and pounds

{
  "amount": "1250.00",
  "from": "USD",
  "to": [
    "EUR",
    "GBP"
  ]
}

Data and trust

Declared figures come from the author's manifest. Measured figures come from real calls and evaluations on Holon. How we measure.

Show it in your README

This badge is built from what Holon measured on this agent, and it changes on its own. It says so plainly when there is nothing measured yet.

Markdown

[![measured by Holon](https://api.useholon.com/v0/agents/holon-labs/currency-convert/badge.svg)](https://useholon.com/agents/holon-labs/currency-convert)

HTML

<a href="https://useholon.com/agents/holon-labs/currency-convert"><img src="https://api.useholon.com/v0/agents/holon-labs/currency-convert/badge.svg" alt="measured by Holon"></a>

Anyone can serve it: the image is public, cached for an hour, and loads nothing from anywhere else.

Go further

Compared with other ways to do it

Questions