allratestoday

README

AllRatesToday Go SDK — allratestoday-go

The official Go client for the AllRatesToday currency API. A small, zero-dependency wrapper over net/http for Go services and CLI tools that need real-time, historical or time-series exchange rates without hand-rolling request and response types.

🚀 Features

• ⚡ Real-time rates — latest mid-market rates for any base currency
• 🌍 160+ currencies — the full list is available from the API via Symbols
• 📅 Historical data — rates for a single past date, an arbitrary date range, or a preset period (1d, 7d, 30d, 1y)
• 💱 Conversion — convert an amount between two currencies in one call
• 🧩 Typed responses — every endpoint decodes into a documented struct with JSON tags
• 🛡️ Typed errors — non-2xx responses surface as a *allratestoday.Error with status code and body
• ⏱️ Context-aware — every method takes a context.Context for timeouts and cancellation
• 🔧 Functional options — WithBaseURL and WithHTTPClient for testing and custom transports
• 📦 Zero dependencies — standard library only (net/http + encoding/json)
• 💹 Mid-market rates — no retail spread baked in

🔑 Get your API key

Create a free key at allratestoday.com/register. Keys look like art_live_..., and the SDK sends yours as a Bearer token in the Authorization header on every request.

📦 Installation

go get github.com/AllRates-Today/allratestoday-go

Requires Go 1.22 or later. No third-party dependencies.

🏁 Quick start

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	allratestoday "github.com/AllRates-Today/allratestoday-go"
)

func main() {
	client := allratestoday.NewClient(os.Getenv("ALLRATES_API_KEY"))
	ctx := context.Background()

	// Latest rates for a base currency
	rates, err := client.Latest(ctx, "USD", []string{"EUR", "GBP"})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("Base:", rates.Base)
	fmt.Println("Rates:", rates.Rates)

	// Convert an amount
	result, err := client.Convert(ctx, "USD", "EUR", 100)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("100 USD = %.2f EUR\n", result.Result)
}

📚 API reference

Construct a client with allratestoday.NewClient(apiKey, opts...). Every method takes a context.Context first and returns a typed response pointer plus an error.

Method	Endpoint	Returns
Latest(ctx, base, symbols)	GET /v1/latest	*LatestResponse
Convert(ctx, from, to, amount)	GET /v1/convert	*ConvertResponse
Historical(ctx, date, base, symbols)	GET /v1/historical	*HistoricalResponse
TimeSeries(ctx, startDate, endDate, base, symbols)	GET /v1/timeseries	*TimeSeriesResponse
Symbols(ctx)	GET /v1/symbols	*SymbolsResponse
GetRate(ctx, from, to)	GET /v1/rate	*RateResponse
GetHistoricalRates(ctx, source, target, period)	GET /v1/historical-rates	*HistoricalRatesResponse

symbols parameters take a []string; pass nil for every available currency.

Latest(ctx, base, symbols)

Most recent rates for a base currency.

// All currencies
rates, err := client.Latest(ctx, "USD", nil)

// Specific currencies only
rates, err := client.Latest(ctx, "USD", []string{"EUR", "GBP", "JPY"})
fmt.Println(rates.Date, rates.Rates)

Convert(ctx, from, to, amount)

Convert an amount between two currencies.

result, err := client.Convert(ctx, "USD", "EUR", 250)
fmt.Println(result.Rate, result.Result)

Historical(ctx, date, base, symbols)

Rates as of a specific historical date (YYYY-MM-DD).

rates, err := client.Historical(ctx, "2025-01-15", "USD", []string{"EUR", "GBP"})
fmt.Println(rates.Date, rates.Rates)

TimeSeries(ctx, startDate, endDate, base, symbols)

Rates across a date range, keyed by date.

series, err := client.TimeSeries(ctx, "2025-01-01", "2025-01-31", "USD", []string{"EUR", "GBP"})
for date, dayRates := range series.Rates {
	fmt.Println(date, dayRates)
}

Symbols(ctx)

Every supported currency code with its details.

symbols, err := client.Symbols(ctx)
for code, info := range symbols.Symbols {
	fmt.Println(code, info.Name)
}

GetRate(ctx, from, to)

A single currency pair.

rate, err := client.GetRate(ctx, "USD", "EUR")
fmt.Println("USD/EUR:", rate.Rate)

GetHistoricalRates(ctx, source, target, period)

A pair's history over a preset period — "1d", "7d", "30d" or "1y". Returns a slice of HistoricalRatePoint (Date / Rate pairs).

history, err := client.GetHistoricalRates(ctx, "USD", "EUR", "30d")
for _, point := range history.Rates {
	fmt.Println(point.Date, point.Rate)
}

Options

Override the default host (https://allratestoday.com) or the HTTP client:

client := allratestoday.NewClient("art_live_your_api_key",
	allratestoday.WithBaseURL("https://custom.example.com"),
	allratestoday.WithHTTPClient(&http.Client{Timeout: 5 * time.Second}),
)

The default HTTP client uses a 10-second timeout; use context.WithTimeout for per-request deadlines.

🗺️ Currencies covered

160+ currencies, including 🇺🇸 USD, 🇪🇺 EUR, 🇬🇧 GBP and 🇯🇵 JPY. Call Symbols for the authoritative, always-current list rather than hard-coding one.

🛡️ Error handling

Non-2xx API responses come back as a *allratestoday.Error carrying the HTTP status code and response body; transport and decode failures are wrapped standard errors. Use errors.As to branch:

rates, err := client.Latest(ctx, "USD", nil)
if err != nil {
	var apiErr *allratestoday.Error
	if errors.As(err, &apiErr) {
		log.Fatalf("API error %d: %s", apiErr.StatusCode, apiErr.Message)
	}
	log.Fatalf("request failed: %v", err) // network, timeout, or parse failure
}
fmt.Println(rates.Rates)

💡 Notes

• Concurrency. A Client is safe for concurrent use by multiple goroutines — create one and share it.
• Cancellation. Every method takes a context.Context, so timeouts and cancellation compose with the rest of your service.
• Tests. Run the unit tests with go test ./.... They use httptest and never touch the network; set ALLRATES_API_KEY to also run the live smoke test.

🤖 Use it from an AI agent

The same rates are available to coding agents and LLM tools without a second integration:

• Claude Code plugin (no key): /plugin marketplace add AllRates-Today/claude-code-plugin then /plugin install allratestoday@allratestoday
• Hosted MCP endpoint: https://allratestoday.com/api/mcp — Streamable HTTP, keyless, nothing to install
• Local MCP servers: npx -y @allratestoday/mcp-server (live mid-market rates) · npx -y @allratestoday/central-bank-mcp (official central-bank rates)
• Trial key for agents, no signup: POST https://allratestoday.com/api/agent/keys (send Content-Type: application/json) returns a 100-call key valid 7 days, enough to try history and dated tables; both MCP servers expose it as request_trial_key
• Daily Reference Rate (first published 2026-10-12): one fixed USD table per business day, the 16:00 London median of minute samples, never revised — keyless at https://allratestoday.com/api/open/reference-rate, get_reference_rate in the MCP server
• Machine-readable site guide: llms.txt

🔗 Links

• Website: allratestoday.com
• API docs: allratestoday.com/docs
• Free API key: allratestoday.com/register
• Package docs: pkg.go.dev/github.com/AllRates-Today/allratestoday-go
• Repository: github.com/AllRates-Today/allratestoday-go
• Status: allratestoday.com/status
• Support: allratestoday.com/contact

📜 License

MIT — see LICENSE.

Documentation

Overview

Package allratestoday is the official Go client for the AllRatesToday exchange rate API (https://allratestoday.com). It provides access to real-time mid-market exchange rates for 160+ currencies, plus historical data, time series and conversion.

Create a free API key at https://allratestoday.com/register. Keys look like "art_live_...", and the client sends yours as a Bearer token in the Authorization header on every request.

client := allratestoday.NewClient("art_live_your_api_key")
rates, err := client.Latest(context.Background(), "USD", []string{"EUR", "GBP"})

Index

• Constants
• type Client
  • func NewClient(apiKey string, opts ...Option) *Client
  • func (c *Client) Convert(ctx context.Context, from, to string, amount float64) (*ConvertResponse, error)
  • func (c *Client) GetHistoricalRates(ctx context.Context, source, target, period string) (*HistoricalRatesResponse, error)
  • func (c *Client) GetRate(ctx context.Context, from, to string) (*RateResponse, error)
  • func (c *Client) Historical(ctx context.Context, date, base string, symbols []string) (*HistoricalResponse, error)
  • func (c *Client) Latest(ctx context.Context, base string, symbols []string) (*LatestResponse, error)
  • func (c *Client) Symbols(ctx context.Context) (*SymbolsResponse, error)
  • func (c *Client) TimeSeries(ctx context.Context, startDate, endDate, base string, symbols []string) (*TimeSeriesResponse, error)
• type ConvertResponse
• type CurrencySymbol
• type Error
  • func (e *Error) Error() string
• type HistoricalRatePoint
• type HistoricalRatesResponse
• type HistoricalResponse
• type LatestResponse
• type Option
  • func WithBaseURL(baseURL string) Option
  • func WithHTTPClient(httpClient *http.Client) Option
• type RateResponse
• type SymbolsResponse
• type TimeSeriesResponse

Constants

const DefaultBaseURL = "https://allratestoday.com"

DefaultBaseURL is the production API host.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is the AllRatesToday API client. Create one with NewClient. A Client is safe for concurrent use by multiple goroutines.

func NewClient

func NewClient(apiKey string, opts ...Option) *Client

NewClient returns a Client that authenticates with the given API key. Get a free key at https://allratestoday.com/register.

func (*Client) Convert

func (c *Client) Convert(ctx context.Context, from, to string, amount float64) (*ConvertResponse, error)

Convert converts an amount from one currency to another.

func (*Client) GetHistoricalRates

func (c *Client) GetHistoricalRates(ctx context.Context, source, target, period string) (*HistoricalRatesResponse, error)

GetHistoricalRates returns a currency pair's history over a preset period: "1d", "7d", "30d" or "1y".

func (*Client) GetRate

func (c *Client) GetRate(ctx context.Context, from, to string) (*RateResponse, error)

GetRate returns the exchange rate for a single currency pair.

func (*Client) Historical

func (c *Client) Historical(ctx context.Context, date, base string, symbols []string) (*HistoricalResponse, error)

Historical returns exchange rates as of a specific past date (YYYY-MM-DD). Pass a nil or empty symbols slice for every currency.

func (*Client) Latest

func (c *Client) Latest(ctx context.Context, base string, symbols []string) (*LatestResponse, error)

Latest returns the most recent exchange rates for a base currency. Pass a nil or empty symbols slice to receive every available currency.

func (*Client) Symbols

func (c *Client) Symbols(ctx context.Context) (*SymbolsResponse, error)

Symbols lists every supported currency code with its details.

func (*Client) TimeSeries

func (c *Client) TimeSeries(ctx context.Context, startDate, endDate, base string, symbols []string) (*TimeSeriesResponse, error)

TimeSeries returns exchange rates across a date range, keyed by date. Dates are YYYY-MM-DD. Pass a nil or empty symbols slice for every currency.

type ConvertResponse

type ConvertResponse struct {
	Success bool    `json:"success"`
	From    string  `json:"from"`
	To      string  `json:"to"`
	Amount  float64 `json:"amount"`
	Result  float64 `json:"result"`
	Rate    float64 `json:"rate"`
}

ConvertResponse is the response from GET /v1/convert.

type CurrencySymbol

type CurrencySymbol struct {
	Code string `json:"code"`
	Name string `json:"name"`
}

CurrencySymbol describes one supported currency.

type Error

type Error struct {
	// StatusCode is the HTTP status code returned by the API.
	StatusCode int
	// Message is the response body (usually a JSON error payload).
	Message string
}

Error is returned when the API responds with a non-2xx status code.

func (*Error) Error

func (e *Error) Error() string

type HistoricalRatePoint

type HistoricalRatePoint struct {
	Date string  `json:"date"`
	Rate float64 `json:"rate"`
}

HistoricalRatePoint is a single date/rate observation in a HistoricalRatesResponse.

type HistoricalRatesResponse

type HistoricalRatesResponse struct {
	Success bool                  `json:"success"`
	Source  string                `json:"source"`
	Target  string                `json:"target"`
	Period  string                `json:"period"`
	Rates   []HistoricalRatePoint `json:"rates"`
}

HistoricalRatesResponse is the response from GET /v1/historical-rates (a currency pair over a preset period).

type HistoricalResponse

type HistoricalResponse struct {
	Success bool               `json:"success"`
	Base    string             `json:"base"`
	Date    string             `json:"date"`
	Rates   map[string]float64 `json:"rates"`
}

HistoricalResponse is the response from GET /v1/historical.

type LatestResponse

type LatestResponse struct {
	Success bool               `json:"success"`
	Base    string             `json:"base"`
	Date    string             `json:"date"`
	Rates   map[string]float64 `json:"rates"`
}

LatestResponse is the response from GET /v1/latest.

type Option

type Option func(*Client)

Option configures a Client created by NewClient.

func WithBaseURL

func WithBaseURL(baseURL string) Option

WithBaseURL overrides the default API host (useful for testing or a self-hosted deployment).

func WithHTTPClient

func WithHTTPClient(httpClient *http.Client) Option

WithHTTPClient replaces the underlying *http.Client (custom timeouts, proxies, instrumentation, ...).

type RateResponse

type RateResponse struct {
	Success bool    `json:"success"`
	From    string  `json:"from"`
	To      string  `json:"to"`
	Rate    float64 `json:"rate"`
	Date    string  `json:"date"`
}

RateResponse is the response from GET /v1/rate (single pair).

type SymbolsResponse

type SymbolsResponse struct {
	Success bool                      `json:"success"`
	Symbols map[string]CurrencySymbol `json:"symbols"`
}

SymbolsResponse is the response from GET /v1/symbols.

type TimeSeriesResponse

type TimeSeriesResponse struct {
	Success   bool                          `json:"success"`
	Base      string                        `json:"base"`
	StartDate string                        `json:"start_date"`
	EndDate   string                        `json:"end_date"`
	Rates     map[string]map[string]float64 `json:"rates"`
}

TimeSeriesResponse is the response from GET /v1/timeseries. Rates is keyed by date (YYYY-MM-DD), then by currency code.