Currex SDK

Currex is a lightweight Go SDK for working with exchange rates and currency conversion using the FastForex API.

The SDK provides a convenient and type-safe wrapper around the FastForex REST API and uses decimal.Decimal for precise financial calculations.

Features

• Get exchange rates between two currencies
• Get rates for multiple currencies
• Retrieve all available rates for a base currency
• Exchange rate matrix support
• Many-to-one currency rates
• Historical exchange rates
• Time series exchange rates
• Precise currency conversion using decimal arithmetic
• Context support for request cancellation and timeouts

Installation

go get github.com/Sayfargo/currex-sdk

Dependencies

Currex uses the following external library for precise decimal arithmetic:

• shopspring/decimal — arbitrary-precision fixed-point decimal numbers for financial calculations.

This avoids floating-point precision issues commonly encountered in financial applications.

API Provider

Currex is built on top of the FastForex API and provides a convenient, type-safe Go interface for working with exchange rates and currency conversion.

Official website: https://www.fastforex.io/

API documentation: https://www.fastforex.io/docs/

To use the SDK, you'll need a valid FastForex API key.

Quick Start

package main

import (
	"context"
	"fmt"

	"github.com/Sayfargo/currex-sdk"
)

func main() {
	client, err := currex.NewClient("your-api-key")
	if err != nil {
		log.Fatal(err)
	}

	rate, err := client.GetRate(
		context.Background(),
		"USD",
		"EUR",
	)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(rate.Value)
}

Creating a Client

client, err := currex.NewClient("your-api-key")
if err != nil {
	log.Fatal(err)
}

Examples

Get Exchange Rate

rate, err := client.GetRate(
	context.Background(),
	"USD",
	"EUR",
)
if err != nil {
	return err
}

fmt.Println(rate.Value)

Get Multiple Rates

rates, err := client.GetMultiRates(
	context.Background(),
	"USD",
	"EUR",
	"GBP",
	"JPY",
)
if err != nil {
	return err
}

fmt.Println(rates.Results)

Get Matrix Rates

matrix, err := client.GetMatrixRates(
	context.Background(),
	[]string{"USD", "EUR"},
	[]string{"GBP", "CHF"},
)
if err != nil {
	return err
}

rate, ok := matrix.Get("USD", "GBP")
if ok {
	fmt.Println(rate)
}

Currency Conversion

conversion, err := client.Convert(
	context.Background(),
	"BTC",
	"USD",
	decimal.NewFromFloat(0.42),
)
if err != nil {
	return err
}

fmt.Println(conversion.Result)

Historical Rates

rates, err := client.GetHistorical(
	context.Background(),
	time.Date(2026, 6, 11, 0, 0, 0, 0, time.UTC),
	"USD",
)
if err != nil {
	return err
}

fmt.Println(rates.Results["EUR"])

Time Series

series, err := client.GetTimeSeries(
	context.Background(),
	"USD",
	"EUR",
)
if err != nil {
	return err
}

rate, ok := series.On(
	time.Date(2026, 6, 11, 0, 0, 0, 0, time.UTC),
)
if ok {
	fmt.Println(rate)
}

Available Methods

Method	Description
GetRate()	Get exchange rate between two currencies
GetMultiRates()	Get rates for multiple currencies
GetAllRates()	Get all available rates for a base currency
GetMatrixRates()	Get matrix of exchange rates
GetManyToOneRates()	Get rates from multiple currencies to one currency
GetHistorical()	Get historical exchange rates
GetTimeSeries()	Get time-series exchange rates
Convert()	Convert an amount using precise decimal arithmetic

Precision

Currex uses decimal.Decimal instead of float64 for all public financial calculations and exchange rate values.

This helps avoid rounding errors and precision loss when working with money.

Error Handling

All SDK methods return typed errors when possible and follow standard Go error wrapping practices.

rate, err := client.GetRate(ctx, "USD", "EUR")
if err != nil {
	return err
}

Context Support

Every request accepts a context.Context.

ctx, cancel := context.WithTimeout(
	context.Background(),
	5*time.Second,
)
defer cancel()

rate, err := client.GetRate(
	ctx,
	"USD",
	"EUR",
)

License

MIT