Handles currency amounts, provides currency information and formatting

# currency [![Build](https://github.com/bojanz/currency/actions/workflows/build.yml/badge.svg)](https://github.com/bojanz/currency/actions/workflows/build.yml) [![Coverage Status](https://coveralls.io/repos/github/bojanz/currency/badge.svg?branch=master)](https://coveralls.io/github/bojanz/currency?branch=master) [![Go Report Card](https://goreportcard.com/badge/github.com/bojanz/currency)](https://goreportcard.com/report/github.com/bojanz/currency) [![PkgGoDev](https://pkg.go.dev/badge/github.com/bojanz/currency)](https://pkg.go.dev/github.com/bojanz/currency)

Handles currency amounts, provides currency information and formatting.

Powered by CLDR v48, in just ~40kb of data.

Backstory: https://bojanz.github.io/price-currency-handling-go/

## Features

1. All currency codes, their numeric codes and fraction digits.
2. Currency symbols and formats for all locales.
3. Country mapping (country code => currency code).
4. Amount struct, with value semantics (Fowler's Money pattern)
5. Formatter, for formatting amounts and parsing formatted amounts.
6. Ability to register custom currencies, or override existing ones.

```go
    amount, _ := currency.NewAmount("275.98", "EUR")
    total, _ := amount.Mul("4")

    locale := currency.NewLocale("fr")
    formatter := currency.NewFormatter(locale)
    fmt.Println(formatter.Format(total)) // 1 103,92 €

    // Convert the amount to Iranian rial and show it in Farsi.
    total, _ = total.Convert("IRR", "45.538")
    total = total.Round()
    locale = currency.NewLocale("fa")
    formatter = currency.NewFormatter(locale)
    fmt.Println(formatter.Format(total)) // ‎ریال ۵۰٬۲۷۰
```

## Design goals

### Real decimal implementation under the hood.

Currency amounts can't be floats. Storing integer minor units (2.99 => 299)
becomes problematic once there are multiple currencies (difficult to sort in the
DB), or there is a need for sub-minor-unit precision (due to merchant or tax
requirements, etc). A real arbitrary-precision decimal type is required. Since
Go doesn't have one natively, a userspace implementation is used, provided by
the [cockroachdb/apd](https://github.com/cockroachdb/apd) package. The Amount struct provides an easy to use
abstraction on top of it, allowing the underlying implementation to be replaced
in the future without a backwards compatibility break.

### Smart filtering of CLDR data.

The "modern" subset of CLDR locales is used, reducing the list from ~560 to ~370 locales.

Once gathered, locales are filtered to remove all data not used by this package,
and then deduplicated by parent (e.g. don't keep `fr-CH` if `fr` has the
same data).

Currency symbols are grouped together to avoid repetition. For example:

    "ARS": {
        {"ARS", []string{"en", "fr-CA"}},
        {"$", []string{"es-AR"}},
        {"$AR", []string{"fr"}},
    }

Currency names are not included because they are rarely shown, but need
significant space. Instead, they can be fetched on the frontend via [Intl.DisplayNames](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DisplayNames).

### Easy to compare.

Amount structs can be compared via [google/go-cmp](https://github.com/google/go-cmp) thanks to the built-in Equal() method.

### Usable with a PostgreSQL composite type.

Thanks to the driver.Valuer and sql.Scanner interfaces, applications using the [pgx](https://github.com/jackc/pgx) driver can store amounts in a composite type.

Example schema:
```
CREATE TYPE price AS (
   number NUMERIC,
   currency_code TEXT
);

CREATE TABLE products (
   id CHAR(26) PRIMARY KEY,
   name TEXT NOT NULL,
   price price NOT NULL,
   created_at TIMESTAMPTZ NOT NULL,
   updated_at TIMESTAMPTZ
);
```
Note that the number and currency_code columns can have any name, only their ordering matters.

Example struct:
```go
type Product struct {
	ID          string
	Name        string
	Price       currency.Amount
	CreatedAt   time.Time
	UpdatedAt   time.Time
}
```

Example scan:
```go
p := Product{}
row := tx.QueryRow(ctx, `SELECT id, name, price, created_at, updated_at FROM products WHERE id = $1`, id)
err := row.Scan(&p.ID, &p.Name, &p.Price, &p.CreatedAt, &p.UpdatedAt)
```

See our [database integration notes](https://github.com/bojanz/currency/wiki/Database-integration-notes) for other examples (MySQL/MariaDB, SQLite).


currency

Arbitrary-precision fixed-point decimal numbers

# decimal

[![ci](https://github.com/shopspring/decimal/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/shopspring/decimal/actions/workflows/ci.yml)
[![GoDoc](https://godoc.org/github.com/shopspring/decimal?status.svg)](https://godoc.org/github.com/shopspring/decimal) 
[![Go Report Card](https://goreportcard.com/badge/github.com/shopspring/decimal)](https://goreportcard.com/report/github.com/shopspring/decimal)

Arbitrary-precision fixed-point decimal numbers in go.

_Note:_ Decimal library can "only" represent numbers with a maximum of 2^31 digits after the decimal point.

## Features

 * The zero-value is 0, and is safe to use without initialization
 * Addition, subtraction, multiplication with no loss of precision
 * Division with specified precision
 * Database/sql serialization/deserialization
 * JSON and XML serialization/deserialization

## Install

Run `go get github.com/shopspring/decimal`

## Requirements 

Decimal library requires Go version `>=1.10`

## Documentation

http://godoc.org/github.com/shopspring/decimal


## Usage

```go
package main

import (
	"fmt"
	"github.com/shopspring/decimal"
)

func main() {
	price, err := decimal.NewFromString("136.02")
	if err != nil {
		panic(err)
	}

	quantity := decimal.NewFromInt(3)

	fee, _ := decimal.NewFromString(".035")
	taxRate, _ := decimal.NewFromString(".08875")

	subtotal := price.Mul(quantity)

	preTax := subtotal.Mul(fee.Add(decimal.NewFromFloat(1)))

	total := preTax.Mul(taxRate.Add(decimal.NewFromFloat(1)))

	fmt.Println("Subtotal:", subtotal)                      // Subtotal: 408.06
	fmt.Println("Pre-tax:", preTax)                         // Pre-tax: 422.3421
	fmt.Println("Taxes:", total.Sub(preTax))                // Taxes: 37.482861375
	fmt.Println("Total:", total)                            // Total: 459.824961375
	fmt.Println("Tax rate:", total.Sub(preTax).Div(preTax)) // Tax rate: 0.08875
}
```

## Alternative libraries

When working with decimal numbers, you might face problems this library is not perfectly suited for. 
Fortunately, thanks to the wonderful community we have a dozen other libraries that you can choose from.  
Explore other alternatives to find the one that best fits your needs :)  

* [cockroachdb/apd](https://github.com/cockroachdb/apd) - arbitrary precision, mutable and rich API similar to `big.Int`, more performant than this library 
* [alpacahq/alpacadecimal](https://github.com/alpacahq/alpacadecimal) - high performance, low precision (12 digits), fully compatible API with this library 
* [govalues/decimal](https://github.com/govalues/decimal) - high performance, zero-allocation, low precision (19 digits)
* [greatcloak/decimal](https://github.com/greatcloak/decimal) - fork focusing on billing and e-commerce web application related use cases, includes out-of-the-box BSON marshaling support

## FAQ

#### Why don't you just use float64?

Because float64 (or any binary floating point type, actually) can't represent
numbers such as `0.1` exactly.

Consider this code: http://play.golang.org/p/TQBd4yJe6B You might expect that
it prints out `10`, but it actually prints `9.999999999999831`. Over time,
these small errors can really add up!

#### Why don't you just use big.Rat?

big.Rat is fine for representing rational numbers, but Decimal is better for
representing money. Why? Here's a (contrived) example:

Let's say you use big.Rat, and you have two numbers, x and y, both
representing 1/3, and you have `z = 1 - x - y = 1/3`. If you print each one
out, the string output has to stop somewhere (let's say it stops at 3 decimal
digits, for simplicity), so you'll get 0.333, 0.333, and 0.333. But where did
the other 0.001 go?

Here's the above example as code: http://play.golang.org/p/lCZZs0w9KE

With Decimal, the strings being printed out represent the number exactly. So,
if you have `x = y = 1/3` (with precision 3), they will actually be equal to
0.333, and when you do `z = 1 - x - y`, `z` will be equal to .334. No money is
unaccounted for!

You still have to be careful. If you want to split a number `N` 3 ways, you
can't just send `N/3` to three different people. You have to pick one to send
`N - (2/3*N)` to. That person will receive the fraction of a penny remainder.

But, it is much easier to be careful with Decimal than with big.Rat.

#### Why isn't the API similar to big.Int's?

big.Int's API is built to reduce the number of memory allocations for maximal
performance. This makes sense for its use-case, but the trade-off is that the
API is awkward and easy to misuse.

For example, to add two big.Ints, you do: `z := new(big.Int).Add(x, y)`. A
developer unfamiliar with this API might try to do `z := a.Add(a, b)`. This
modifies `a` and sets `z` as an alias for `a`, which they might not expect. It
also modifies any other aliases to `a`.

Here's an example of the subtle bugs you can introduce with big.Int's API:
https://play.golang.org/p/x2R_78pa8r

In contrast, it's difficult to make such mistakes with decimal. Decimals
behave like other go numbers types: even though `a = b` will not deep copy
`b` into `a`, it is impossible to modify a Decimal, since all Decimal methods
return new Decimals and do not modify the originals. The downside is that
this causes extra allocations, so Decimal is less performant.  My assumption
is that if you're using Decimals, you probably care more about correctness
than performance.

## License

The MIT License (MIT)

This is a heavily modified fork of [fpd.Decimal](https://github.com/oguzbilgic/fpd), which was also released under the MIT License.


decimal

High performant & accurate currency computation package.

<img src="https://user-images.githubusercontent.com/1092882/84137258-11328400-aa6a-11ea-94d9-9d58e56a0ea3.png" alt="webgo gopher" width="256px"/>

[![](https://github.com/naughtygopher/currency/actions/workflows/go.yml/badge.svg?branch=master)](https://github.com/naughtygopher/currency/actions)
[![Go Reference](https://pkg.go.dev/badge/github.com/naughtygopher/currency.svg)](https://pkg.go.dev/github.com/naughtygopher/currency)
[![Go Report Card](https://goreportcard.com/badge/github.com/naughtygopher/currency)](https://goreportcard.com/report/github.com/naughtygopher/currency)
[![Coverage Status](https://coveralls.io/repos/github/naughtygopher/currency/badge.svg?branch=master)](https://coveralls.io/github/naughtygopher/currency?branch=master)
[![Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go/tree/main?tab=readme-ov-file#financial)

## Currency v2.0.1

Currency package helps you do currency computations accurately. `Currency` struct holds all the data required to define a currency.

```
type Currency struct {
	// Code represents the international currency code
	Code string
	// Symbol is the respective currency symbol
	Symbol string
	// Main represents the main value of the currency
	Main int
	// Fractional represents the fractional/sub unit of the currency
	Fractional uint
	// FUName is the name of the fractional/sub unit of the currency. e.g. paise
	FUName string
	// FUShare represents the no.of fractional/sub units that make up 1 main unit. e.g. ₹1 = 100 paise
	// Number of fractional units that make up 1 unit of the main value
	FUShare uint
	// PrefixSymbol if true will prefix the symbol when stringified
	PrefixSymbol bool
	// SuffixSymbol if true will suffix the symbol when stringified
	SuffixSymbol bool
}
```

### New(main int, fractional int, code, symbol string, funame string, fushare uint)

New returns a pointer of currency instance created based on the values provided

```
main - Main/Super unit of the currency
fractional - Subunit/fractional unit of the currency
code - is the currency code according to [ISO 4217 specification](https://en.wikipedia.org/wiki/ISO_4217)
symbol - Unicode symbol of the currency
funame - Name of the fractional/sub unit
fushare - Number of fractional/sub units that make up 1 unit of the main/super unit
```

_IMPORTANT! Fractional unit can be negative only when the main value is 0. If the main value is not 0, fractional unit's negative sign is ignored._

### Parsers & convenience methods

1. `NewFractional(fractional int, symbol string, fulabel string, fushare uint)` returns a currency struct instance, given a currency's total value represented by the fractional unit
2. `ParseString(value string, code, symbol string, fulabel string, fushare uint)` returns a currency struct instance, given a currency value represented as string
3. `ParseFloat64(value float64, code, symbol string, funame string, fushare uint)` returns a currency struct instance, given a currency value represented in float64

### Computational methods

IMPORTANT: Computation is supported only between same type of currencies (i.e. currency codes should be same)

1. `c1.Add(c2 currency)` add c2 to c1, and update c1
2. `c1.AddInt(main int, fractional int)` add the currency equivalent of the main & fractional int to c1
3. `c1.Subtract(c2 currency)` subtract c2 from c1, and update c1
4. `c1.SubtractIn(main int, fractional int)` subtract the currency equivalent of the main & fractional int from c1
5. `c1.Multiply(n int)` multiply c1 by n, where n is an integer
6. `c1.MultiplyFloat64(n float64)` multiply c1 by n, where n is a float64 value
7. `c1.UpdateWithFractional(ftotal int)` would update the the value of c1, where _ftotal_ is the total value of the currency in fractional unit. e.g. INR, `UpdateWithFractional(100)` would set the main value as `1` and fractional unit as `0`
8. `c1.FractionalTotal() int` returns the total value of the currency in its fractional unit. e.g. INR, if the Main value is `1` and fractional unit is `0`, it would return `100`, i.e. 100 paise
9. `c1.Percent(n float64) currency` returns a new currency instance which is n percentage of c1
10. `c1.Divide(n int, retain bool)[]currency, ok ` returns a slice of currency of size n. `ok` if returned as `true` means the currency value was perfectly divisible by n. If `retain` is true,
 then `c1` will have the remainder value after dividing otherwise it is distributed among the returned currencies.

#### Why does `Divide(n int, retain bool)` return a slice of currencies?

`Divide` unlike other operations, cannot be rounded off. If it is rounded, it would result in currency peddling.

e.g. ₹1/- (INR 1) is to be divided by 3. There are 2 options of dividing this by 3.

 1. Set 33 paise per split, and retain the remaining 1 paise at source. (`Divide(n, true)`)

 2. Set 1 of the split with an extra value, i.e. 34 + 33 + 33. (`Divide(n, false)`)

### Multiple currency representations

1. `c1.String()`, returns a string representation of the currency value
2. `c1.Float64()`, returns a float64 representation of the currency value

## Benchmarks

How to run?

`$ go test -bench=.`

Results when run on a MacBook Pro (13-inch, Early 2015), CPU: 2.7 GHz Intel Core i5, RAM: 8 GB 1867 MHz DDR3, Graphics: Intel Iris Graphics 6100 1536 MB

```
BenchmarkNew-4 	20000000	 67.3 ns/op
BenchmarkNewFractional-4 	20000000	 65.9 ns/op
BenchmarkParseFloat64-4 	20000000	 87.4 ns/op
BenchmarkParseString-4 	 3000000	 544 ns/op
BenchmarkString-4 	10000000	 211 ns/op
BenchmarkStringNoPrefix-4 	10000000	 164 ns/op
BenchmarkFloat64-4 	2000000000	 0.34 ns/op
BenchmarkFractionalTotal-4 	2000000000	 0.33 ns/op
BenchmarkUpdateWithFractional-4 	100000000	 10.3 ns/op
BenchmarkAdd-4 	100000000	 20.8 ns/op
BenchmarkAddInt-4 	100000000	 18.9 ns/op
BenchmarkSubtract-4 	100000000	 21.2 ns/op
BenchmarkSubtractInt-4 	100000000	 18.3 ns/op
BenchmarkMultiply-4 	100000000	 16.2 ns/op
BenchmarkMultiplyFloat64-4 	50000000	 30.1 ns/op
BenchmarkPercent-4 	20000000	 67.1 ns/op
BenchmarkDivide-4 	10000000	 155 ns/op
```

## References

1. [Ref - Sub unit or fractional unit](<https://en.wikipedia.org/wiki/Denomination_(currency)>)
2. [Ref - Currencies](https://en.wikipedia.org/wiki/Currency) - about currencies
3. [Non-decimal sub unit in currencies are only used by 2 countries today](https://en.wikipedia.org/wiki/Non-decimal_currency). These are getting phased out.

_IMPORTANT! This package does not support sub units which are not a power of 10. Nor does it support currencies with more than 1 sub unit_

## The gopher

The gopher used here was created using [Gopherize.me](https://gopherize.me/). Deal with currency professionally just like this gopher!

Immutable decimal numbers with panic-free arithmetic

# decimal

[![githubb]][github]
[![codecovb]][codecov]
[![goreportb]][goreport]
[![godocb]][godoc]
[![licenseb]][license]
[![versionb]][version]
[![awesomeb]][awesome]

Package decimal implements correctly rounded decimal floating-point numbers for Go.
This package is designed specifically for use in transactional financial systems.

## Key Features

- **BSON, JSON, XML, SQL** - Implements the necessary interfaces for direct compatibility
  with the [mongo-driver/bson], [encoding/json], [encoding/xml], and [database/sql] packages.
- **No Heap Allocations** - Optimized to avoid heap allocations,
  preventing garbage collector impact during arithmetic operations.
- **Correct Rounding** - For all methods, the result is the one that would
  be obtained if the true mathematical value were rounded to 19 digits of
  precision using the [half-to-even] rounding (a.k.a. "banker's rounding").
- **No Panics** - All methods are panic-free, returning errors instead of crashing
  your application in cases such as overflow or division by zero.
- **Immutability** - Once set, a decimal remains constant,
  ensuring safe concurrent access across goroutines.
- **Simple String Representation** - Decimals are represented in a straightforward
  format avoiding the complexities of scientific or engineering notations.
- **Rigorous Testing** - All methods are cross-validated against
  the [cockroachdb/apd] and [shopspring/decimal] packages through extensive [fuzz testing].

## Getting Started

### Installation

To add the decimal package to your Go workspace:

```bash
go get github.com/govalues/decimal
```

### Basic Usage

Create decimal values using one of the constructors.
After creating a decimal, you can perform various operations as shown below:

```go
package main

import (
    "fmt"
    "github.com/govalues/decimal"
)

func main() {
    // Constructors
    d, _ := decimal.New(8, 0)               // d = 8
    e, _ := decimal.Parse("12.5")           // e = 12.5
    f, _ := decimal.NewFromFloat64(2.567)   // f = 2.567
    g, _ := decimal.NewFromInt64(7, 896, 3) // g = 7.896

    // Arithmetic operations
    fmt.Println(d.Add(e))              // 8 + 12.5
    fmt.Println(d.Sub(e))              // 8 - 12.5
    fmt.Println(d.SubAbs(e))           // abs(8 - 12.5)

    fmt.Println(d.Mul(e))              // 8 * 12.5
    fmt.Println(d.AddMul(e, f))        // 8 + 12.5 * 2.567
    fmt.Println(d.SubMul(e, f))        // 8 - 12.5 * 2.567
    fmt.Println(d.PowInt(2))           // 8²

    fmt.Println(d.Quo(e))              // 8 / 12.5
    fmt.Println(d.AddQuo(e, f))        // 8 + 12.5 / 2.567
    fmt.Println(d.SubQuo(e, f))        // 8 - 12.5 / 2.567
    fmt.Println(d.QuoRem(e))           // 8 div 12.5, 8 mod 12.5
    fmt.Println(d.Inv())               // 1 / 8

    fmt.Println(decimal.Sum(d, e, f))  // 8 + 12.5 + 2.567
    fmt.Println(decimal.Mean(d, e, f)) // (8 + 12.5 + 2.567) / 3
    fmt.Println(decimal.Prod(d, e, f)) // 8 * 12.5 * 2.567

    // Transcendental functions
    fmt.Println(e.Sqrt())              // √12.5
    fmt.Println(e.Exp())               // exp(12.5)
    fmt.Println(e.Expm1())             // exp(12.5) - 1
    fmt.Println(e.Log())               // ln(12.5)
    fmt.Println(e.Log1p())             // ln(12.5 + 1)
    fmt.Println(e.Log2())              // log₂(12.5)
    fmt.Println(e.Log10())             // log₁₀(12.5)
    fmt.Println(e.Pow(d))              // 12.5⁸

    // Rounding to 2 decimal places
    fmt.Println(g.Round(2))            // 7.90
    fmt.Println(g.Ceil(2))             // 7.90
    fmt.Println(g.Floor(2))            // 7.89
    fmt.Println(g.Trunc(2))            // 7.89

    // Conversions
    fmt.Println(f.Int64(9))            // 2 567000000
    fmt.Println(f.Float64())           // 2.567
    fmt.Println(f.String())            // 2.567

    // Formatting
    fmt.Printf("%.2f", f)              // 2.57
    fmt.Printf("%.2k", f)              // 256.70%
}
```

## Documentation

For detailed documentation and additional examples, visit the package
[documentation](https://pkg.go.dev/github.com/govalues/decimal#section-documentation).
For examples related to financial calculations, see the `money` package
[documentation](https://pkg.go.dev/github.com/govalues/money#section-documentation).

## Comparison

Comparison with other popular packages:

| Feature              | govalues  | [cockroachdb/apd] v3.2.1 | [shopspring/decimal] v1.4.0 |
| -------------------- | --------- | ------------------------ | --------------------------- |
| Correctly Rounded    | Yes       | No                       | No                          |
| Speed                | High      | Medium                   | Low[^reason]                |
| Heap Allocations     | No        | Medium                   | High                        |
| Precision            | 19 digits | Arbitrary                | Arbitrary                   |
| Panic Free           | Yes       | Yes                      | No[^divzero]                |
| Mutability           | Immutable | Mutable[^reason]         | Immutable                   |
| Mathematical Context | Implicit  | Explicit                 | Implicit                    |

[^reason]: decimal package was created simply because [shopspring/decimal] was
too slow and [cockroachdb/apd] was mutable.

[^divzero]: [shopspring/decimal] panics on division by zero.

### Benchmarks

```text
goos: linux
goarch: amd64
pkg: github.com/govalues/decimal-tests
cpu: AMD Ryzen 7 3700C  with Radeon Vega Mobile Gfx 
```

| Test Case | Expression            | govalues | [cockroachdb/apd] v3.2.1 | [shopspring/decimal] v1.4.0 | govalues vs cockroachdb | govalues vs shopspring |
| --------- | --------------------- | -------: | -----------------------: | --------------------------: | ----------------------: | ---------------------: |
| Add       | 5 + 6                 |   16.06n |                   74.88n |                     140.90n |                +366.22% |               +777.33% |
| Mul       | 2 * 3                 |   16.93n |                   62.20n |                     146.00n |                +267.40% |               +762.37% |
| Quo       | 2 / 4 (exact)         |   59.52n |                  176.95n |                     657.40n |                +197.30% |              +1004.50% |
| Quo       | 2 / 3 (inexact)       |  391.60n |                  976.80n |                    2962.50n |                +149.39% |               +656.42% |
| PowInt    | 1.1^60                |  950.90n |                 3302.50n |                    4599.50n |                +247.32% |               +383.73% |
| PowInt    | 1.01^600              |    3.45µ |                   10.67µ |                      18.67µ |                +209.04% |               +440.89% |
| PowInt    | 1.001^6000            |    5.94µ |                   20.50µ |                     722.22µ |                +244.88% |             +12052.44% |
| Sqrt      | √2                    |    3.40µ |                    4.96µ |                    2101.86µ |                 +46.00% |             +61755.71% |
| Exp       | exp(0.5)              |    8.35µ |                   39.28µ |                      20.06µ |                +370.58% |               +140.32% |
| Log       | ln(0.5)               |   54.89µ |                  129.01µ |                     151.55µ |                +135.03% |               +176.10% |
| Parse     | 1                     |   16.52n |                   76.30n |                     136.55n |                +362.00% |               +726.82% |
| Parse     | 123.456               |   47.37n |                  176.90n |                     242.60n |                +273.44% |               +412.14% |
| Parse     | 123456789.1234567890  |   85.49n |                  224.15n |                     497.95n |                +162.19% |               +482.47% |
| String    | 1                     |    5.11n |                   19.57n |                     198.25n |                +283.21% |              +3783.07% |
| String    | 123.456               |   35.78n |                   77.12n |                     228.85n |                +115.52% |               +539.51% |
| String    | 123456789.1234567890  |   70.72n |                  239.10n |                     337.25n |                +238.12% |               +376.91% |
| Telco     | (see [specification]) |  137.00n |                  969.40n |                    3981.00n |                +607.33% |              +2804.78% |

The benchmark results shown in the table are provided for informational purposes only and may vary depending on your specific use case.

[codecov]: https://codecov.io/gh/govalues/decimal
[codecovb]: https://img.shields.io/codecov/c/github/govalues/decimal/main?color=brightcolor
[goreport]: https://goreportcard.com/report/github.com/govalues/decimal
[goreportb]: https://goreportcard.com/badge/github.com/govalues/decimal
[github]: https://github.com/govalues/decimal/actions/workflows/go.yml
[githubb]: https://img.shields.io/github/actions/workflow/status/govalues/decimal/go.yml
[godoc]: https://pkg.go.dev/github.com/govalues/decimal#section-documentation
[godocb]: https://img.shields.io/badge/go.dev-reference-blue
[version]: https://go.dev/dl
[versionb]: https://img.shields.io/github/go-mod/go-version/govalues/decimal?label=go
[license]: https://en.wikipedia.org/wiki/MIT_License
[licenseb]: https://img.shields.io/github/license/govalues/decimal?color=blue
[awesome]: https://github.com/avelino/awesome-go#financial
[awesomeb]: https://awesome.re/mentioned-badge.svg
[cockroachdb/apd]: https://pkg.go.dev/github.com/cockroachdb/apd
[shopspring/decimal]: https://pkg.go.dev/github.com/shopspring/decimal
[mongo-driver/bson]: https://pkg.go.dev/go.mongodb.org/mongo-driver/v2/bson#ValueUnmarshaler
[encoding/json]: https://pkg.go.dev/encoding/json#Unmarshaler
[encoding/xml]: https://pkg.go.dev/encoding#TextUnmarshaler
[database/sql]: https://pkg.go.dev/database/sql#Scanner
[specification]: https://speleotrove.com/decimal/telcoSpec.html
[fuzz testing]: https://github.com/govalues/decimal-tests
[half-to-even]: https://en.wikipedia.org/wiki/Rounding#Rounding_half_to_even


Fast and precise serialization and arithmetic for small fixed-point decimals

# Fixed-Point Decimals

> To use in money, look at [github.com/nikolaydubina/fpmoney](https://github.com/nikolaydubina/fpmoney)

> _Be Precise. Using floats to represent currency is almost criminal. — Robert.C.Martin, "Clean Code" p.301_


 ✨ Sponsored by <a href="https://apps.apple.com/app/id6738306589">NDX AI Shopping Assistant</a>


[![codecov](https://codecov.io/gh/nikolaydubina/fpdecimal/branch/main/graph/badge.svg?token=0pf0P5qloX)](https://codecov.io/gh/nikolaydubina/fpdecimal)
[![Go Reference](https://pkg.go.dev/badge/github.com/nikolaydubina/fpdecimal.svg)](https://pkg.go.dev/github.com/nikolaydubina/fpdecimal)
[![Awesome](https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg)](https://github.com/avelino/awesome-go#financial)
[![Go Report Card](https://goreportcard.com/badge/github.com/nikolaydubina/fpdecimal)](https://goreportcard.com/report/github.com/nikolaydubina/fpdecimal)
[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/nikolaydubina/fpdecimal/badge)](https://securityscorecards.dev/viewer/?uri=github.com/nikolaydubina/fpdecimal)

* `int64` inside
* does not use `float` neither in parsing nor printing
* as fast as `int64` in parsing, printing, arithmetics — 3x faser `float`, 20x faster [shopspring/decimal](https://github.com/shopspring/decimal), 30x faster `fmt`
* zero-overhead
* preventing error-prone fixed-point arithmetics
* Fuzz tests, Benchmarks
* JSON
* 200LOC

```go
import fp "github.com/nikolaydubina/fpdecimal"

var BuySP500Price = fp.FromInt(9000)

input := []byte(`{"sp500": 9000.023}`)

type Stocks struct {
 SP500 fp.Decimal `json:"sp500"`
}
var v Stocks
if err := json.Unmarshal(input, &v); err != nil {
 log.Fatal(err)
}

var amountToBuy fp.Decimal
if v.SP500.GreaterThan(BuySP500Price) {
 amountToBuy = amountToBuy.Add(v.SP500.Mul(fp.FromInt(2)))
}

fmt.Println(amountToBuy)
// Output: 18000.046
```

### Implementation

Parsing and Printing is expensive operation and requires a lot of code.
However, if you know that your numbers are always small and simple and you do not care or do not permit lots of fractions like `-1234.567`, then parsing and printing can be greatly simplified.
Code is heavily influenced by hot-path from Go core `strconv` package.

It is wrapped into struct to prevent bugs:
- block multiplication by `fpdecimal` type, which leads to increase in decimal fractions and loose of precision
- block additions of untyped constants, which leads to errors if you forget to scale by factor

### Benchmarks

Parse
```
$ go test -bench=BenchmarkParse -benchtime=5s -benchmem .
goos: darwin
goarch: arm64
pkg: github.com/nikolaydubina/fpdecimal
BenchmarkParse/fromString/small-10 534307098 11.36 ns/op 0 B/op 0 allocs/op
BenchmarkParse/fromString/large-10 254741558 23.42 ns/op 0 B/op 0 allocs/op
BenchmarkParse/UnmarshalJSON/small-10 816873427 7.32 ns/op 0 B/op 0 allocs/op
BenchmarkParse/UnmarshalJSON/large-10 272173255 22.16 ns/op 0 B/op 0 allocs/op
BenchmarkParse_int_strconv_Atoi/small-10 1000000000 4.87 ns/op 0 B/op 0 allocs/op
BenchmarkParse_int_strconv_Atoi/large-10 420536834 14.31 ns/op 0 B/op 0 allocs/op
BenchmarkParse_int_strconv_ParseInt/small/int32-10 561137575 10.67 ns/op 0 B/op 0 allocs/op
BenchmarkParse_int_strconv_ParseInt/small/int64-10 564200026 10.64 ns/op 0 B/op 0 allocs/op
BenchmarkParse_int_strconv_ParseInt/large/int64-10 219626983 27.17 ns/op 0 B/op 0 allocs/op
BenchmarkParse_float_strconv_ParseFloat/small/float32-10 345666214 17.36 ns/op 0 B/op 0 allocs/op
BenchmarkParse_float_strconv_ParseFloat/small/float64-10 339620222 17.68 ns/op 0 B/op 0 allocs/op
BenchmarkParse_float_strconv_ParseFloat/large/float32-10 128824344 46.68 ns/op 0 B/op 0 allocs/op
BenchmarkParse_float_strconv_ParseFloat/large/float64-10 128140617 46.89 ns/op 0 B/op 0 allocs/op
BenchmarkParse_float_fmt_Sscanf/small-10 21202892 281.6 ns/op 69 B/op 2 allocs/op
BenchmarkParse_float_fmt_Sscanf/large-10 10074237 599.2 ns/op 88 B/op 3 allocs/op
PASS
ok github.com/nikolaydubina/fpdecimal 116.249s
```

Print
```
$ go test -bench=BenchmarkPrint -benchtime=5s -benchmem .
goos: darwin
goarch: arm64
pkg: github.com/nikolaydubina/fpdecimal
BenchmarkPrint/small-10 191982066 31.24 ns/op 8 B/op 1 allocs/op
BenchmarkPrint/large-10 150874335 39.89 ns/op 24 B/op 1 allocs/op
BenchmarkPrint_int_strconv_Itoa/small-10 446302868 13.39 ns/op 3 B/op 0 allocs/op
BenchmarkPrint_int_strconv_Itoa/large-10 237484774 25.20 ns/op 18 B/op 1 allocs/op
BenchmarkPrint_int_strconv_FormatInt/small-10 444861666 13.70 ns/op 3 B/op 0 allocs/op
BenchmarkPrint_float_strconv_FormatFloat/small/float32-10 55003357 104.2 ns/op 31 B/op 2 allocs/op
BenchmarkPrint_float_strconv_FormatFloat/small/float64-10 43565430 137.4 ns/op 31 B/op 2 allocs/op
BenchmarkPrint_float_strconv_FormatFloat/large/float32-10 64069650 92.07 ns/op 48 B/op 2 allocs/op
BenchmarkPrint_float_strconv_FormatFloat/large/float64-10 68441746 87.36 ns/op 48 B/op 2 allocs/op
BenchmarkPrint_float_fmt_Sprintf/small-10 46503666 127.7 ns/op 16 B/op 2 allocs/op
BenchmarkPrint_float_fmt_Sprintf/large-10 51764224 115.8 ns/op 28 B/op 2 allocs/op
PASS
ok github.com/nikolaydubina/fpdecimal 79.192s
```

Arithmetics
```
$ go test -bench=BenchmarkArithmetic -benchtime=5s -benchmem .
goos: darwin
goarch: arm64
pkg: github.com/nikolaydubina/fpdecimal
BenchmarkArithmetic/add-10 1000000000 0.316 ns/op 0 B/op 0 allocs/op
BenchmarkArithmetic/div-10 1000000000 0.950 ns/op 0 B/op 0 allocs/op
BenchmarkArithmetic/divmod-10 1000000000 1.890 ns/op 0 B/op 0 allocs/op
BenchmarkArithmetic_int64/add-10 1000000000 0.314 ns/op 0 B/op 0 allocs/op
BenchmarkArithmetic_int64/div-10 1000000000 0.316 ns/op 0 B/op 0 allocs/op
BenchmarkArithmetic_int64/divmod-10 1000000000 1.261 ns/op 0 B/op 0 allocs/op
BenchmarkArithmetic_int64/mod-10 1000000000 0.628 ns/op 0 B/op 0 allocs/op
PASS
ok github.com/nikolaydubina/fpdecimal 6.721s
```

## References

- [Fixed-Point Arithmetic Wiki](https://en.wikipedia.org/wiki/Fixed-point_arithmetic)
- [shopspring/decimal](https://github.com/shopspring/decimal)

## Appendix A: Comparison to other libraries

- https://github.com/shopspring/decimal solves arbitrary precision, fpdecimal solves only simple small decimals
- https://github.com/Rhymond/go-money solves typed number (currency), decodes through `interface{}` and float64, no precision in decoding, expects encoding to be in cents

## Appendix B: Benchmarking [shopspring/decimal](https://github.com/shopspring/decimal)

`2022-05-28`
```
$ go test -bench=. -benchtime=5s -benchmem ./...
goos: darwin
goarch: arm64
pkg: github.com/shopspring/decimal
BenchmarkNewFromFloatWithExponent-10 59701516 97.7 ns/op 106 B/op 4 allocs/op
BenchmarkNewFromFloat-10 14771503 410.3 ns/op 67 B/op 2 allocs/op
BenchmarkNewFromStringFloat-10 16246342 375.2 ns/op 175 B/op 5 allocs/op
Benchmark_FloorFast-10 1000000000 2.1 ns/op 0 B/op 0 allocs/op
Benchmark_FloorRegular-10 53857244 106.3 ns/op 112 B/op 6 allocs/op
Benchmark_DivideOriginal-10 7 715322768 ns/op 737406446 B/op 30652495 allocs/op
Benchmark_DivideNew-10 22 262893689 ns/op 308046721 B/op 12054905 allocs/op
BenchmarkDecimal_RoundCash_Five-10 9311530 636.5 ns/op 616 B/op 28 allocs/op
Benchmark_Cmp-10 44 133191579 ns/op 24 B/op 1 allocs/op
Benchmark_decimal_Decimal_Add_different_precision-10 31561636 176.6 ns/op 280 B/op 9 allocs/op
Benchmark_decimal_Decimal_Sub_different_precision-10 36892767 164.4 ns/op 240 B/op 9 allocs/op
Benchmark_decimal_Decimal_Add_same_precision-10 134831919 44.9 ns/op 80 B/op 2 allocs/op
Benchmark_decimal_Decimal_Sub_same_precision-10 134902627 43.1 ns/op 80 B/op 2 allocs/op
BenchmarkDecimal_IsInteger-10 92543083 66.1 ns/op 8 B/op 1 allocs/op
BenchmarkDecimal_NewFromString-10 827455 7382 ns/op 3525 B/op 216 allocs/op
BenchmarkDecimal_NewFromString_large_number-10 212538 28836 ns/op 16820 B/op 360 allocs/op
BenchmarkDecimal_ExpHullAbraham-10 10000 572091 ns/op 486628 B/op 568 allocs/op
BenchmarkDecimal_ExpTaylor-10 26343 222915 ns/op 431226 B/op 3172 allocs/op
PASS
ok github.com/shopspring/decimal 123.541sa
```

## Appendix C: Why this is good fit for money?

There are only ~200 currencies in the world.
All currencies have at most 3 decimal digits, thus it is sufficient to handle 3 decimal fractions.
Next, currencies without decimal digits are typically 1000x larger than dollar, but even then maximum number that fits into `int64` (without 3 decimal fractions) is `9 223 372 036 854 775.807` which is ~9 quadrillion. This should be enough for most operations with money.

## Appendix D: Is it safe to use arithmetic operators in Go?

Sort of... 

In one of iterations, I did Type Alias, but it required some effort to use it carefully.

Operations with defined types (variables) will fail.
```go
var a int64
var b fpdecimal.FromInt(1000)

// does not compile
a + b
```

However, untyped constants will be resolved to underlying type `int64` and will be allowed. 
```go
const a 10000
var b fpdecimal.FromInt(1000)

// compiles
a + b

// also compiles
b - 42

// this one too
b *= 23
```

Is this a problem? 
* For multiplication and division - yes, it can be. You have to be careful not to multiply two `fpdecimal` numbers, since scaling factor will quadruple. Multiplying by constants is ok tho.
* For addition substraction - yes, it can be. You have to be careful and remind yourself that constants would be reduced 1000x.

Both of this can be addressed at compile time by providing linter.
This can be also addressed by wrapping into a struct and defining methods.
Formed is hard to achieve in Go, due to lack of operator overload and lots of work required to write AST parser.
Later has been implemented in this pacakge, and, as benchmarks show, without any extra memory or calls overhead as compared to `int64`.

## Appendix E: Print into destination

To avoid mallocs, it is advantageous to print formatted value to pre-allocated destination.
Similarly, to `strconv.AppendInt`, we provide `AppendFixedPointDecimal`.
This is utilized in `github.com/nikolaydubina/fpmoney` package.

```
BenchmarkFixedPointDecimalToString/small-10 28522474 35.43 ns/op 24 B/op 1 allocs/op
BenchmarkFixedPointDecimalToString/large-10 36883687 32.32 ns/op 24 B/op 1 allocs/op
BenchmarkAppendFixedPointDecimal/small-10 38105520 30.51 ns/op 117 B/op 0 allocs/op
BenchmarkAppendFixedPointDecimal/large-10 55147478 29.52 ns/op 119 B/op 0 allocs/op
```

## Appendix F: DivMod notation

In early versions, `Div` and `Mul` operated on `int` and `Div` returned remainder.
As recommended by @vanodevium and more in line with other common libraries, notation is changed.
Bellow is survey as of 2023-05-18.

Go, https://pkg.go.dev/math/big
```go
func (z *Int) Div(x, y *Int) *Int
func (z *Int) DivMod(x, y, m *Int) (*Int, *Int)
func (z *Int) Mod(x, y *Int) *Int
```

Go, github.com/shopspring/decimal
```go
func (d Decimal) Div(d2 Decimal) Decimal
// X no DivMod
func (d Decimal) Mod(d2 Decimal) Decimal
func (d Decimal) DivRound(d2 Decimal, precision int32) Decimal
```

Python, https://docs.python.org/3/library/decimal.html
```python
divide(x, y) number
divide_int(x, y) number // truncates
divmod(x, y) number
remainder(x, y) number
```

Pytorch, https://pytorch.org/docs/stable/generated/torch.div.html
```python
torch.div(input, other, *, rounding_mode=None, out=None) → [Tensor] // discards remainder
torch.remainder(input, other, *, out=None) → [Tensor] // remainder
```

numpy, https://numpy.org/doc/stable/reference/generated/numpy.divmod.html
```python
np.divmod(x, y) (number, number) // is equivalent to (x // y, x % y
np.mod(x, y) number
np.remainder(x, y) number
np.divide(x, y) number
np.true_divide(x, y) number // same as divide
np.floor_divide(x, y) number // rounding down
```

## Appendix G: generics switch for decimal counting

Go does not support numerics in templates. However, defining multiple types each associated with specific number of decimals and passing them to functions and defining constraint as union of these types — is an attractive option.
This does not work well since Go does not support switch case (casting generic) back to integer well.

## Appendix H: `string` vs `[]byte` in interface

The typical usage of parsing number is through some JSON or other mechanism. Those APIs are dealing with `[]byte`.
Now, conversion from `[]byte` to `string` requires to copy data, since `string` is immutable.
To improve performance, we are using `[]byte` in signatures.

Using `string`
```
BenchmarkParse/fromString/small-10 831217767 7.07 ns/op 0 B/op 0 allocs/op
BenchmarkParse/fromString/large-10 275009497 21.79 ns/op 0 B/op 0 allocs/op
BenchmarkParse/UnmarshalJSON/small-10 553035127 10.98 ns/op 0 B/op 0 allocs/op
BenchmarkParse/UnmarshalJSON/large-10 248815030 24.14 ns/op 0 B/op 0 allocs/op
```

Using `[]byte`
```
BenchmarkParse/fromString/small-10 523937236 11.32 ns/op 0 B/op 0 allocs/op
BenchmarkParse/fromString/large-10 257542226 23.23 ns/op 0 B/op 0 allocs/op
BenchmarkParse/UnmarshalJSON/small-10 809793006 7.31 ns/op 0 B/op 0 allocs/op
BenchmarkParse/UnmarshalJSON/large-10 272087984 22.04 ns/op 0 B/op 0 allocs/op
```

## Appendix F: dynamic pkg level fraction digits

This is very bug prone. In fact, this was observd in production, [issue](https://github.com/nikolaydubina/fpdecimal/issues/26).

Consider:

1. package A. init map with .FromInt
2. package B imports A and sets in init() num fraction digits
3. package B sees values in package A initialized with different fraction digits
4. 💥

Therefore, we are inlining fraction digits into most common fractions.

- 3 is enough to represent all currencies
- 3 is enough for SI units conversion ladder
- 6 is enough for 10cm x 10cm of (lat,long)

fpdecimal

Fast and simple ISO4217 fixed-point decimal money

<img width="300" height="300" src="https://github.com/nikolaydubina/fpmoney/assets/2933061/022c83e3-8a14-4e8f-b1b7-94ab262fa590">



 ✨ Sponsored by <a href="https://apps.apple.com/app/id6738306589">NDX AI Shopping Assistant</a>


## 🧧 Fixed-Point Decimal Money

[![codecov](https://codecov.io/gh/nikolaydubina/fpmoney/branch/master/graph/badge.svg?token=Eh52jhLERp)](https://codecov.io/gh/nikolaydubina/fpmoney)
[![Go Report Card](https://goreportcard.com/badge/github.com/nikolaydubina/fpmoney)](https://goreportcard.com/report/github.com/nikolaydubina/fpmoney)
[![Go Reference](https://pkg.go.dev/badge/github.com/nikolaydubina/fpmoney.svg)](https://pkg.go.dev/github.com/nikolaydubina/fpmoney)
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go)
[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/nikolaydubina/fpmoney/badge)](https://securityscorecards.dev/viewer/?uri=github.com/nikolaydubina/fpmoney)

> _**Be Precise:** using floats to represent currency is almost criminal. — Robert.C.Martin, "Clean Code" p.301_

* as fast as `int64`
* no `float` in parsing nor printing, does not leak precision
* `ISO 4217`[^1][^2] currency
* block mismatched currency arithmetics
* 100 LOC
* fuzz tests

```go
var BuySP500Price = fpmoney.FromInt(9000, fpmoney.SGD)

input := []byte(`{"sp500": {"amount": 9000.02, "currency": "SGD"}}`)

type Stonks struct {
 SP500 fpmoney.Amount `json:"sp500"`
}
var v Stonks
if err := json.Unmarshal(input, &v); err != nil {
 log.Fatal(err)
}

amountToBuy := fpmoney.FromInt(0, fpmoney.SGD)
if v.SP500.GreaterThan(BuySP500Price) {
 amountToBuy = amountToBuy.Add(v.SP500.Mul(2))
}

fmt.Println(amountToBuy)
// Output: 18000.04 SGD
```

### Ultra Small Fractions

Some denominations have very low fractions.
Storing them `int64` you would get.

- `BTC` _satoshi_ is `1 BTC = 100,000,000 satoshi`, which is still enough for ~`92,233,720,368 BTC`.
- `ETH` _wei_ is `1 ETH = 1,000,000,000,000,000,000 wei`, which is ~`9 ETH`. If you deal with _wei_, you may consider `bigint` or multiple `int64`. In fact, official Ethereum code is in Go and it is using bigint ([code](https://github.com/ethereum/go-ethereum/blob/master/params/denomination.go)).

### Benchmarks

```bash
$ go test -bench=. -benchmem .
goos: darwin
goarch: arm64
pkg: github.com/nikolaydubina/fpmoney
cpu: Apple M3 Max
BenchmarkCurrency_UnmarshalText-16 711695404 1.610 ns/op 0 B/op 0 allocs/op
BenchmarkCurrency_AppendText-16 446232057 2.698 ns/op 0 B/op 0 allocs/op
BenchmarkCurrency_MarshalText-16 81956246 13.99 ns/op 8 B/op 1 allocs/op
BenchmarkCurrency_String-16 1000000000 1.064 ns/op 0 B/op 0 allocs/op
BenchmarkArithmetic/add-16 924924993 1.305 ns/op 0 B/op 0 allocs/op
BenchmarkJSON/small/encode-16 6004620 198.5 ns/op 160 B/op 3 allocs/op
BenchmarkJSON/small/decode-16 5047149 238.7 ns/op 152 B/op 2 allocs/op
BenchmarkJSON/large/encode-16 4739722 255.7 ns/op 176 B/op 3 allocs/op
BenchmarkJSON/large/decode-16 3737406 315.3 ns/op 152 B/op 2 allocs/op
BenchmarkBinary/small/encode-16 132380481 9.044 ns/op 16 B/op 1 allocs/op
BenchmarkBinary/small/decode-16 100000000 10.80 ns/op 16 B/op 1 allocs/op
BenchmarkBinary/large/encode-16 133549021 8.995 ns/op 16 B/op 1 allocs/op
BenchmarkBinary/large/decode-16 100000000 10.61 ns/op 16 B/op 1 allocs/op
PASS
ok github.com/nikolaydubina/fpmoney 15.804s
```

## References and Related Work

- [ferdypruis/iso4217](https://github.com/ferdypruis/iso4217) was a good inspiration and reference material. it was used in early version as well. it is well maintained and fast library for currencies. 
- `github.com/shopspring/decimal`: fixed precision; faster printing/parsing/arithmetics; currency handling 
- `github.com/Rhymond/go-money`: does not use `float` or `interface{}` in parsing; currency is enum
- `github.com/ferdypruis/iso4217`: skipped deprecated currencies to fit into `uint8` and smaller struct size
- https://en.wikipedia.org/wiki/ISO_4217

[^1]: excluding currencies with 4+ minor units `CLF`, `UYW`
[^2]: excluding deprecated currencies `HRD`, `HRK`, `SLL`, `ZWL`

fpmoney

# accounting - money and currency formatting for golang
[![Build Status](https://travis-ci.org/leekchan/accounting.svg?branch=master)](https://travis-ci.org/leekchan/accounting)
[![Coverage Status](https://coveralls.io/repos/leekchan/accounting/badge.svg?branch=master&service=github)](https://coveralls.io/github/leekchan/accounting?branch=master)
[![GoDoc](https://godoc.org/github.com/leekchan/accounting?status.svg)](https://godoc.org/github.com/leekchan/accounting)

accounting is a library for money and currency formatting. (inspired by [accounting.js](https://github.com/openexchangerates/accounting.js))


## Quick Start

```
go get github.com/leekchan/accounting
```

example.go

```Go
package main

import (
 "fmt"
 "math/big"

 "github.com/shopspring/decimal"
 "github.com/leekchan/accounting"
)

func main() {
 ac := accounting.Accounting{Symbol: "$", Precision: 2}
 fmt.Println(ac.FormatMoney(123456789.213123)) // "$123,456,789.21"
 fmt.Println(ac.FormatMoney(12345678)) // "$12,345,678.00"
 fmt.Println(ac.FormatMoney(big.NewRat(77777777, 3))) // "$25,925,925.67"
 fmt.Println(ac.FormatMoney(big.NewRat(-77777777, 3))) // "-$25,925,925.67"
 fmt.Println(ac.FormatMoneyBigFloat(big.NewFloat(123456789.213123))) // "$123,456,789.21"
 fmt.Println(ac.FormatMoneyDecimal(decimal.New(123456789.213123, 0))) // "$123,456,789.21"

 ac = accounting.Accounting{Symbol: "€", Precision: 2, Thousand: ".", Decimal: ","}
 fmt.Println(ac.FormatMoney(4999.99)) // "€4.999,99"

 // Or retrieve currency info from Locale struct
 lc := LocaleInfo["USD"]
 ac = accounting.Accounting{Symbol: lc.ComSymbol, Precision: 2, Thousand: lc.ThouSep, Decimal: lc.DecSep}
 fmt.Println(ac.FormatMoney(500000)) // "$500,000.00"

 ac = accounting.Accounting{Symbol: "£ ", Precision: 0}
 fmt.Println(ac.FormatMoney(500000)) // "£ 500,000"

 ac = accounting.Accounting{Symbol: "GBP", Precision: 0,
 Format: "%s %v", FormatNegative: "%s (%v)", FormatZero: "%s --"}
 fmt.Println(ac.FormatMoney(1000000)) // "GBP 1,000,000"
 fmt.Println(ac.FormatMoney(-5000)) // "GBP (5,000)"
 fmt.Println(ac.FormatMoney(0)) // "GBP --"

 ac = accounting.DefaultAccounting("GBP", 2)
 fmt.Println(ac.FormatMoney(1000000)) // "GBP 1,000,000"
 fmt.Println(ac.FormatMoney(-5000)) // "GBP (5,000)"
 fmt.Println(ac.FormatMoney(0)) // "GBP --"

 ac = accounting.NewAccounting("GBP", 2, ",", ".", "%s %v", "%s (%v)", "%s --")
 fmt.Println(ac.FormatMoney(1000000)) // "GBP 1,000,000"
 fmt.Println(ac.FormatMoney(-5000)) // "GBP (5,000)"
 fmt.Println(ac.FormatMoney(0)) // "GBP --"
}
```

## Caution

Please do not use float64 to count money. Floats can have errors when you perform operations on them. Using [big.Rat](https://golang.org/pkg/math/big/#Rat) (< Go 1.5) or [big.Float](https://golang.org/pkg/math/big/#Float) (>= Go 1.5) is highly recommended.
(accounting supports float64, but it is just for convenience.)

* [FormatMoneyBigFloat(value *big.Float) string](#formatmoneybigfloatvalue-bigfloat-string)
* [FormatMoneyBigRat(value *big.Rat) string](#formatmoneybigratvalue-bigrat-string)

## Initialization

### Accounting struct

```Go
type Accounting struct {
 Symbol string // currency symbol (required)
 Precision int // currency precision (decimal places) (optional / default: 0)
 Thousand string // thousand separator (optional / default: ,)
 Decimal string // decimal separator (optional / default: .)
 Format string // simple format string allows control of symbol position (%v = value, %s = symbol) (default: %s%v)
 FormatNegative string // format string for negative values (optional / default: strings.Replace(strings.Replace(accounting.Format, "-", "", -1), "%v", "-%v", -1))
 FormatZero string // format string for zero values (optional / default: Format)
}
```

Field | Type | Description | Default | Example
-------------| ------------- | ------------- | ------------- | -------------
Symbol | string | currency symbol | no default value | $
Precision | int | currency precision (decimal places) | 0 | 2
Thousand | string | thousand separator | , | .
Decimal | string | decimal separator | . | ,
Format | string | simple format string allows control of symbol position (%v = value, %s = symbol) | %s%v | %s %v
FormatNegative | string | format string for negative values | strings.Replace(strings.Replace(accounting.Format, "-", "", -1), "%v", "-%v", -1)) | %s (%v)
FormatZero | string | format string for zero values | Format | %s --

**Examples:**

```Go
# Via functions
ac := accounting.DefaultAccounting("$", 2)
ac := accounting.NewAccounting("$", 2, ",", ".", "%s %v", "%s (%v)", "%s --")

# Via Accounting struct
ac := accounting.Accounting{Symbol: "$", Precision: 2}

ac = accounting.Accounting{Symbol: "€", Precision: 2, Thousand: ".", Decimal: ","}

ac = accounting.Accounting{Symbol: "GBP", Precision: 0,
 Format: "%s %v", FormatNegative: "%s (%v)", FormatZero: "%s --"}
```

## SetThousandSeparator(str string)

SetThousandSeparator sets the separator for the thousands separation

## SetDecimalSeparator(str string)

SetDecimalSeparator sets the separator for the decimal separation

## SetFormat(str string)

SetFormat sets the Format default: `%s%v` (%s=Symbol;%v=Value)

## SetFormatNegative(str string)

SetFormatNegative sets the Format for negative values default: `-%s%v` (%s=Symbol;%v=Value)

## SetFormatZero(str string)

SetFormatZero sets the Format for zero values default: `%s%v` (%s=Symbol;%v=Value)

### Locale struct

```Go
type Locale struct {
 Name string // currency name
 FractionLength int // default decimal length
 ThouSep string // thousands seperator
 DecSep string // decimal seperator
 SpaceSep string // space seperator
 UTFSymbol string // UTF symbol
 HTMLSymbol string // HTML symbol
 ComSymbol string // Common symbol
 Pre bool // symbol before or after currency
}
```

Field | Type | Description | Default | Example
 -------------| ------------- | ------------- | ------------- | -------------
 Name | string | currency name | no default value | US Dollar 
 FractionLength | int | default precision (decimal places) | no default value | 2
 ThouSep | string | thousand separator | no default value | ,
 DecSep | string | decimal separator | no default value | .
 SpaceSep | string | space separator | no default value | " "
 UTFSymbol | string | UTF symbol | no default value | "0024" 
 HTMLSymbol | string | HTML symbol | no default value | "&#x0024"
 ComSymbol | string | Common symbol | no default value | "$"
 Pre | bool | symbol before currency | no default value | true

**Example:**

```Go
// LocaleInfo map[string]Locale

var lc Locale
if val, ok := LocaleInfo["USD"]; ok {
 lc = val
} else {
 panic("No Locale Info Found")
}

fmt.Println(lc.Name) // "US Dollar"
fmt.Println(lc.FractionLength) // 2
fmt.Println(lc.ThouSep) // ","
fmt.Println(lc.DecSep) // "."
fmt.Println(lc.SpaceSep) // ""
fmt.Println(lc.UTFSymbol) // "0024"
fmt.Println(lc.HTMLSymbol) // "&#x0024"
fmt.Println(lc.ComSymbol) // "$"
fmt.Println(lc.Pre) // true
```
There are currently 181 currencies supported in LocaleInfo

## FormatMoney(value interface{}) string

FormatMoney is a function for formatting numbers as money values, with customisable currency symbol, precision (decimal places), and thousand/decimal separators.

FormatMoney supports various types of value by runtime reflection. If you don't need runtime type evaluation, please refer to FormatMoneyInt, FormatMoneyBigRat, FormatMoneyBigRat, or FormatMoneyFloat64.

* supported value types : int, int8, int16, int32, int64, uint, uint8, uint16, uint32, uint64, float32, float64, *big.Rat

**Examples:**

```Go
ac := accounting.Accounting{Symbol: "$", Precision: 2}
fmt.Println(ac.FormatMoney(123456789.213123)) // "$123,456,789.21"
fmt.Println(ac.FormatMoney(12345678)) // "$12,345,678.00"
fmt.Println(ac.FormatMoney(big.NewRat(77777777, 3))) // "$25,925,925.67"
fmt.Println(ac.FormatMoney(big.NewRat(-77777777, 3))) // "-$25,925,925.67"

ac = accounting.Accounting{Symbol: "€", Precision: 2, Thousand: ".", Decimal: ","}
fmt.Println(ac.FormatMoney(4999.99)) // "€4.999,99"

ac = accounting.Accounting{Symbol: "£ ", Precision: 0}
fmt.Println(ac.FormatMoney(500000)) // "£ 500,000"

ac = accounting.Accounting{Symbol: "GBP", Precision: 0,
 Format: "%s %v", FormatNegative: "%s (%v)", FormatZero: "%s --"}
fmt.Println(ac.FormatMoney(1000000)) // "GBP 1,000,000"
fmt.Println(ac.FormatMoney(-5000)) // "GBP (5,000)"
fmt.Println(ac.FormatMoney(0)) // "GBP --"
```

## FormatMoneyBigFloat(value *big.Float) string

**(>= Go 1.5)**

FormatMoneyBigFloat only supports [*big.Float](https://golang.org/pkg/math/big/#Float) value. It is faster than FormatMoney, because it does not do any runtime type evaluation.

**Examples:**

```Go
ac = accounting.Accounting{Symbol: "$", Precision: 2}
fmt.Println(ac.FormatMoneyBigFloat(big.NewFloat(123456789.213123))) // "$123,456,789.21"
fmt.Println(ac.FormatMoneyBigFloat(big.NewFloat(12345678))) // "$12,345,678.00"

ac = accounting.Accounting{Symbol: "€", Precision: 2, Thousand: ".", Decimal: ","}
fmt.Println(ac.FormatMoneyBigFloat(big.NewFloat(4999.99))) // "€4.999,99"

ac = accounting.Accounting{Symbol: "£ ", Precision: 0}
fmt.Println(ac.FormatMoneyBigFloat(big.NewFloat(500000))) // "£ 500,000"

ac = accounting.Accounting{Symbol: "GBP", Precision: 0,
 Format: "%s %v", FormatNegative: "%s (%v)", FormatZero: "%s --"}
fmt.Println(ac.FormatMoneyBigFloat(big.NewFloat(1000000))) // "GBP 1,000,000"
fmt.Println(ac.FormatMoneyBigFloat(big.NewFloat(-5000))) // "GBP (5,000)"
fmt.Println(ac.FormatMoneyBigFloat(big.NewFloat(0))) // "GBP --"
```

## FormatMoneyInt(value int) string

FormatMoneyInt only supports int value. It is faster than FormatMoney, because it does not do any runtime type evaluation.

**Examples:**

```Go
ac = accounting.Accounting{Symbol: "$", Precision: 2}
fmt.Println(ac.FormatMoneyInt(12345678)) // "$12,345,678.00"

ac = accounting.Accounting{Symbol: "€", Precision: 2, Thousand: ".", Decimal: ","}
fmt.Println(ac.FormatMoneyInt(4999)) // "€4.999,00"

ac = accounting.Accounting{Symbol: "£ ", Precision: 0}
fmt.Println(ac.FormatMoneyInt(500000)) // "£ 500,000"

ac = accounting.Accounting{Symbol: "GBP", Precision: 0,
 Format: "%s %v", FormatNegative: "%s (%v)", FormatZero: "%s --"}
fmt.Println(ac.FormatMoneyInt(1000000)) // "GBP 1,000,000"
fmt.Println(ac.FormatMoneyInt(-5000)) // "GBP (5,000)"
fmt.Println(ac.FormatMoneyInt(0)) // "GBP --"
```

## FormatMoneyBigRat(value *big.Rat) string

FormatMoneyBigRat only supports [*big.Rat](https://golang.org/pkg/math/big/#Rat) value. It is faster than FormatMoney, because it does not do any runtime type evaluation.

**Examples:**

```Go
ac = accounting.Accounting{Symbol: "$", Precision: 2}
fmt.Println(ac.FormatMoneyBigRat(big.NewRat(77777777, 3))) // "$25,925,925.67"
fmt.Println(ac.FormatMoneyBigRat(big.NewRat(-77777777, 3))) // "-$25,925,925.67"

ac = accounting.Accounting{Symbol: "€", Precision: 2, Thousand: ".", Decimal: ","}
fmt.Println(ac.FormatMoneyBigRat(big.NewRat(77777777, 3))) // "€25.925.925,67"

ac = accounting.Accounting{Symbol: "£ ", Precision: 0}
fmt.Println(ac.FormatMoneyBigRat(big.NewRat(77777777, 3))) // "£ 25,925,926"

ac = accounting.Accounting{Symbol: "GBP", Precision: 0,
 Format: "%s %v", FormatNegative: "%s (%v)", FormatZero: "%s --"}
fmt.Println(ac.FormatMoneyBigRat(big.NewRat(77777777, 3))) // "GBP 25,925,926"
fmt.Println(ac.FormatMoneyBigRat(big.NewRat(-77777777, 3))) // "GBP (25,925,926)"
fmt.Println(ac.FormatMoneyBigRat(big.NewRat(0, 3))) // "GBP --"
```

## FormatMoneyFloat64(value float64) string

FormatMoneyFloat64 only supports float64 value. It is faster than FormatMoney, because it does not do any runtime type evaluation.

**Examples:**

```Go
ac = accounting.Accounting{Symbol: "$", Precision: 2}
fmt.Println(ac.FormatMoneyFloat64(123456789.213123)) // "$123,456,789.21"
fmt.Println(ac.FormatMoneyFloat64(12345678)) // "$12,345,678.00"

ac = accounting.Accounting{Symbol: "€", Precision: 2, Thousand: ".", Decimal: ","}
fmt.Println(ac.FormatMoneyFloat64(4999.99)) // "€4.999,99"

ac = accounting.Accounting{Symbol: "£ ", Precision: 0}
fmt.Println(ac.FormatMoneyFloat64(500000)) // "£ 500,000"

ac = accounting.Accounting{Symbol: "GBP", Precision: 0,
 Format: "%s %v", FormatNegative: "%s (%v)", FormatZero: "%s --"}
fmt.Println(ac.FormatMoneyFloat64(1000000)) // "GBP 1,000,000"
fmt.Println(ac.FormatMoneyFloat64(-5000)) // "GBP (5,000)"
fmt.Println(ac.FormatMoneyFloat64(0)) // "GBP --"
```

## FormatNumber(value interface{}, precision int, thousand string, decimal string) string

FormatNumber is a base function of the library which formats a number with custom precision and separators. 

FormatNumber supports various types of value by runtime reflection. If you don't need runtime type evaluation, please refer to FormatNumberInt, FormatNumberBigRat, or FormatNumberFloat64.

* supported value types : int, int8, int16, int32, int64, uint, uint8, uint16, uint32, uint64, float32, float64, *big.Rat

**Examples:**

```Go
fmt.Println(accounting.FormatNumber(123456789.213123, 3, ",", ".")) // "123,456,789.213"
fmt.Println(accounting.FormatNumber(1000000, 3, " ", ",")) // "1 000 000,000"
```

## FormatNumberBigFloat(value *big.Float, precision int, thousand string, decimal string) string

**(>= Go 1.5)**

FormatNumberBigFloat only supports [*big.Float](https://golang.org/pkg/math/big/#Float) value. It is faster than FormatNumber, because it does not do any runtime type evaluation.

**Examples:**

```Go
fmt.Println(accounting.FormatNumberBigFloat(big.NewFloat(123456789.213123), 3, ",", ".")) // "123,456,789.213"
```

## FormatNumberInt(value int, precision int, thousand string, decimal string) string

FormatNumberInt only supports int value. It is faster than FormatNumber, because it does not do any runtime type evaluation.

**Examples:**

```Go
fmt.Println(accounting.FormatNumberInt(123456789, 3, ",", ".")) // "123,456,789.000"
```

## FormatNumberBigRat(value *big.Rat, precision int, thousand string, decimal string) string

FormatNumberBigRat only supports [*big.Rat](https://golang.org/pkg/math/big/#Rat) value. It is faster than FormatNumber, because it does not do any runtime type evaluation.

**Examples:**

```Go
fmt.Println(accounting.FormatNumberBigRat(big.NewRat(77777777, 3), 3, ",", ".")) // "25,925,925.667"
```

## FormatNumberFloat64(value float64, precision int, thousand string, decimal string) string

FormatNumberFloat64 only supports float64 value. It is faster than FormatNumber, because it does not do any runtime type evaluation.

**Examples:**

```Go
fmt.Println(accounting.FormatNumberFloat64(123456789.213123, 3, ",", ".")) // "123,456,789.213"
```

## FormatNumberDecimal(value decimal.Decimal, precision int, thousand string, decimal string) string

FormatNumberDecimal only supports [decimal.Decimal](https://github.com/shopspring/decimal) value. It is faster than FormatNumber, because it does not do any runtime type evaluation.

**Examples:**

```Go
import "github.com/shopspring/decimal"
fmt.Println(accounting.FormatNumberBigDecimal(apd.New(apd.New(4999999, -3), 3, ",", ".")) // "4,999.999"
```

## FormatNumberBigDecimal(value apd.Decimal, precision int, thousand string, decimal string) string

FormatNumberDecimal only supports [apd.Decimal](https://github.com/cockroachdb/apd) value. It is faster than FormatNumber, because it does not do any runtime type evaluation.

**Examples:**

```Go
import "github.com/cockroachdb/apd"
fmt.Println(accounting.FormatNumberDecimal(decimal.New(123456789.213123,3), 3, ",", ".")) // "123,456,789.213"
```

## UnformatNumber(number string, precision int, currency string) string

UnformatNumber is the inverse of FormatNumber. It strips out all currency formatting and returns the number with a point for the decimal seperator. 

**Examples:**

```Go
fmt.Println(accounting.UnformatNumber("$45,000.50", 2, "USD")) // "45000.50"
fmt.Println(accounting.UnformatNumber("EUR 12.500,3474", 3, "EUR")) // "12500.347"
```

accounting

A reader, writer, and validator for Automated Clearing House (ACH) files

A crypto trading bot framework written in Go. Including common crypto exchange API, standard indicators, back-testing and many built-in strategies

bbgo

# Money

![alt text](http://i.imgur.com/c3XmCC6.jpg "Money")

[![Go Report Card](https://goreportcard.com/badge/github.com/rhymond/go-money)](https://goreportcard.com/report/github.com/rhymond/go-money)
[![Coverage Status](https://coveralls.io/repos/github/Rhymond/go-money/badge.svg?branch=master)](https://coveralls.io/github/Rhymond/go-money?branch=master)
[![GoDoc](https://godoc.org/github.com/Rhymond/go-money?status.svg)](https://godoc.org/github.com/Rhymond/go-money)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**GoMoney** provides ability to work with [monetary value using a currency's smallest unit](https://martinfowler.com/eaaCatalog/money.html).
This package provides basic and precise Money operations such as rounding, splitting and allocating.  Monetary values should not be stored as floats due to small rounding differences.

```go
package main

import (
  "log"

  "github.com/Rhymond/go-money"
)

func main() {
    pound := money.New(100, money.GBP)
    twoPounds, err := pound.Add(pound)

    if err != nil {
        log.Fatal(err)
    }

    parties, err := twoPounds.Split(3)

    if err != nil {
        log.Fatal(err)
    }

    parties[0].Display() // £0.67
    parties[1].Display() // £0.67
    parties[2].Display() // £0.66
}

```
Quick start
-
Get the package:

``` bash
$ go get github.com/Rhymond/go-money
```

## Features
* Provides a Money struct which stores information about an Money amount value and its currency.
* Provides a ```Money.Amount``` struct which encapsulates all information about a monetary unit.
* Represents monetary values as integers, in cents. This avoids floating point rounding errors.
* Represents currency as ```Money.Currency``` instances providing a high level of flexibility.

Usage
-
### Initialization
Initialize Money by using smallest unit value (e.g 100 represents 1 pound). Use ISO 4217 Currency Code to set money Currency. Note that constants are also provided for all ISO 4217 currency codes.
```go
pound := money.New(100, money.GBP)
```
Or initialize Money using the direct amount.
```go
quarterEuro := money.NewFromFloat(0.25, money.EUR)
```
Comparison
-
**Go-money** provides base compare operations like:

* Equals
* GreaterThan
* GreaterThanOrEqual
* LessThan
* LessThanOrEqual
* Compare

Comparisons must be made between the same currency units.

```go
pound := money.New(100, money.GBP)
twoPounds := money.New(200, money.GBP)
twoEuros := money.New(200, money.EUR)

pound.GreaterThan(twoPounds) // false, nil
pound.LessThan(twoPounds) // true, nil
twoPounds.Equals(twoEuros) // false, error: Currencies don't match
twoPounds.Compare(pound) // 1, nil
pound.Compare(twoPounds) // -1, nil
pound.Compare(pound) // 0, nil
pound.Compare(twoEuros) // pound.amount, ErrCurrencyMismatch
```
Asserts
-
* IsZero
* IsNegative
* IsPositive

#### Zero value

To assert if Money value is equal to zero use `IsZero()`

```go
pound := money.New(100, money.GBP)
result := pound.IsZero() // false
```

#### Positive value

To assert if Money value is more than zero use `IsPositive()`

```go
pound := money.New(100, money.GBP)
pound.IsPositive() // true
```

#### Negative value

To assert if Money value is less than zero use `IsNegative()`

```go
pound := money.New(100, money.GBP)
pound.IsNegative() // false
```

Operations
-
* Add
* Subtract
* Multiply
* Absolute
* Negative

Comparisons must be made between the same currency units.

#### Addition

Additions can be performed using `Add()`.

```go
pound := money.New(100, money.GBP)
twoPounds := money.New(200, money.GBP)

result, err := pound.Add(twoPounds) // £3.00, nil
```

#### Subtraction

Subtraction can be performed using `Subtract()`.

```go
pound := money.New(100, money.GBP)
twoPounds := money.New(200, money.GBP)

result, err := pound.Subtract(twoPounds) // -£1.00, nil
```

#### Multiplication

Multiplication can be performed using `Multiply()`.

```go
pound := money.New(100, money.GBP)

result := pound.Multiply(2) // £2.00
```

#### Absolute

Return `absolute` value of Money structure

```go
pound := money.New(-100, money.GBP)

result := pound.Absolute() // £1.00
```

#### Negative

Return `negative` value of Money structure

```go
pound := money.New(100, money.GBP)

result := pound.Negative() // -£1.00
```

Allocation
-

* Split
* Allocate

#### Splitting

In order to split Money for parties without losing any pennies due to rounding differences, use `Split()`.

After division leftover pennies will be distributed round-robin amongst the parties. This means that parties listed first will likely receive more pennies than ones that are listed later.

```go
pound := money.New(100, money.GBP)
parties, err := pound.Split(3)

if err != nil {
    log.Fatal(err)
}

parties[0].Display() // £0.34
parties[1].Display() // £0.33
parties[2].Display() // £0.33
```

#### Allocation

To perform allocation operation use `Allocate()`.

It splits money using the given ratios without losing pennies and as Split operations distributes leftover pennies amongst the parties with round-robin principle.

```go
pound := money.New(100, money.GBP)
// Allocate is variadic function which can receive ratios as
// slice (int[]{33, 33, 33}...) or separated by a comma integers
parties, err := pound.Allocate(33, 33, 33)

if err != nil {
    log.Fatal(err)
}

parties[0].Display() // £0.34
parties[1].Display() // £0.33
parties[2].Display() // £0.33
```

Format
-

To format and return Money as a string use `Display()`.

```go
money.New(123456789, money.EUR).Display() // €1,234,567.89
```
To format and return Money as a float64 representing the amount value in the currency's subunit use `AsMajorUnits()`.

```go
money.New(123456789, money.EUR).AsMajorUnits() // 1234567.89
```

Contributing
-
Thank you for considering contributing!
Please use GitHub issues and Pull Requests for contributing.

License
-
The MIT License (MIT). Please see License File for more information.



[![forthebadge](http://forthebadge.com/images/badges/built-with-love.svg)](https://github.com/Rhymond/go-money)


go-money

Client for stock market, forex and crypto data from finnhub.io. Access real-time financial market data from 60+ stock exchanges, 10 forex brokers, and 15+ crypto exchanges.

# go-finnhub

[![GoDoc](https://godoc.org/github.com/m1/go-finnhub?status.svg)](https://godoc.org/github.com/m1/go-finnhub)
[![Build Status](https://travis-ci.org/m1/go-finnhub.svg?branch=master)](https://travis-ci.org/m1/go-finnhub)
[![Go Report Card](https://goreportcard.com/badge/github.com/m1/go-finnhub)](https://goreportcard.com/report/github.com/m1/go-finnhub)
[![Release](https://img.shields.io/github/release/m1/go-finnhub.svg)](https://github.com/m1/go-finnhub/releases/latest)
[![codecov](https://codecov.io/gh/m1/go-finnhub/branch/master/graph/badge.svg)](https://codecov.io/gh/m1/go-finnhub)

__Simple and easy to use client for stock, forex and crpyto data from [finnhub.io](https://finnhub.io/) written in Go. Access real-time market data from 60+ stock exchanges, 10 forex brokers, and 15+ crypto exchanges__

## Installation

`go get github.com/m1/go-finnhub`

## Usage

First sign up for your api token here [finnhub.io](https://finnhub.io/)

Follow this basic example, for more in-depth documentation see the [docs](https://godoc.org/github.com/m1/go-finnhub):
```go
c := client.New("your_token_here")

// Stocks
company, err := c.Stock.GetProfile("AAPL")
ceo, err := c.Stock.GetCEO("AAPL")
recommendation, err := c.Stock.GetRecommendations("AAPL")
target, err := c.Stock.GetPriceTarget("AAPL")
options, err := c.Stock.GetOptionChain("DBD")
peers, err := c.Stock.GetPeers("AAPL")
earnings, err := c.Stock.GetEarnings("AAPL")
candle, err := c.Stock.GetCandle("AAPL", finnhub.CandleResolutionDay, nil)
exchanges, err := c.Stock.GetExchanges()
symbols, err := c.Stock.GetSymbols("US")
gradings, err := c.Stock.GetGradings(&finnhub.GradingParams{Symbol: "AAPL"})

// Crypto
exchanges, err := c.Crypto.GetExchanges()
symbols, err := c.Crypto.GetSymbols("Binance")
candle, err := c.Crypto.GetCandle("BINANCE:BEAMUSDT", finnhub.CandleResolutionMonth, nil)

// Forex
exchanges, err := c.Forex.GetExchanges()
symbols, err := c.Forex.GetSymbols("oanda")
candle, err := c.Forex.GetCandle("OANDA:XAU_GBP", finnhub.CandleResolutionMonth, nil)

// News
news, err := c.News.Get(nil)
news, err = c.News.Get(&finnhub.NewsParams{Category: finnhub.NewsCategoryCrypto})
news, err = c.News.GetCompany("AAPL")
sentiment, err := c.News.GetSentiment("AAPL")
```

go-finnhub

Matching Engine for Limit Order Book in Golang

# Go orderbook

Improved matching engine written in Go (Golang)

[![Go Report Card](https://goreportcard.com/badge/github.com/i25959341/orderbook)](https://goreportcard.com/report/github.com/i25959341/orderbook)
[![GoDoc](https://godoc.org/github.com/i25959341/orderbook?status.svg)](https://godoc.org/github.com/i25959341/orderbook)
[![gocover.run](https://gocover.run/github.com/i25959341/orderbook.svg?style=flat&tag=1.10)](https://gocover.run?tag=1.10&repo=github.com%2Fi25959341%2Forderbook)
[![Stability: Active](https://masterminds.github.io/stability/active.svg)](https://masterminds.github.io/stability/active.html)
[![Build Status](https://travis-ci.org/i25959341/orderbook.svg?branch=master)](https://travis-ci.org/i25959341/orderbook)

## Features

- Standard price-time priority
- Supports both market and limit orders
- Supports order cancelling
- High performance (above 300k trades per second)
- Optimal memory usage
- JSON Marshalling and Unmarsalling
- Calculating market price for definite quantity

## Usage

To start using order book you need to create object:

```go
import (
  "fmt" 
  ob "github.com/muzykantov/orderbook"
)

func main() {
  orderBook := ob.NewOrderBook()
  fmt.Println(orderBook)
}

```

Then you be able to use next primary functions:

```go

func (ob *OrderBook) ProcessLimitOrder(side Side, orderID string, quantity, price decimal.Decimal) (done []*Order, partial *Order, err error) { ... }

func (ob *OrderBook) ProcessMarketOrder(side Side, quantity decimal.Decimal) (done []*Order, partial *Order, quantityLeft decimal.Decimal, err error) { .. }

func (ob *OrderBook) CancelOrder(orderID string) *Order { ... }

```

## About primary functions

### ProcessLimitOrder

```go
// ProcessLimitOrder places new order to the OrderBook
// Arguments:
//      side     - what do you want to do (ob.Sell or ob.Buy)
//      orderID  - unique order ID in depth
//      quantity - how much quantity you want to sell or buy
//      price    - no more expensive (or cheaper) this price
//      * to create new decimal number you should use decimal.New() func
//        read more at https://github.com/shopspring/decimal
// Return:
//      error   - not nil if quantity (or price) is less or equal 0. Or if order with given ID is exists
//      done    - not nil if your order produces ends of anoter order, this order will add to
//                the "done" slice. If your order have done too, it will be places to this array too
//      partial - not nil if your order has done but top order is not fully done. Or if your order is
//                partial done and placed to the orderbook without full quantity - partial will contain
//                your order with quantity to left
//      partialQuantityProcessed - if partial order is not nil this result contains processed quatity from partial order
func (ob *OrderBook) ProcessLimitOrder(side Side, orderID string, quantity, price decimal.Decimal) (done []*Order, partial *Order, err error) { ... }
```

For example:
```
ProcessLimitOrder(ob.Sell, "uinqueID", decimal.New(55, 0), decimal.New(100, 0))

asks: 110 -> 5      110 -> 5
      100 -> 1      100 -> 56
--------------  ->  --------------
bids: 90  -> 5      90  -> 5
      80  -> 1      80  -> 1

done    - nil
partial - nil

```

```
ProcessLimitOrder(ob.Buy, "uinqueID", decimal.New(7, 0), decimal.New(120, 0))

asks: 110 -> 5
      100 -> 1
--------------  ->  --------------
bids: 90  -> 5      120 -> 1
      80  -> 1      90  -> 5
                    80  -> 1

done    - 2 (or more orders)
partial - uinqueID order

```

```
ProcessLimitOrder(ob.Buy, "uinqueID", decimal.New(3, 0), decimal.New(120, 0))

asks: 110 -> 5
      100 -> 1      110 -> 3
--------------  ->  --------------
bids: 90  -> 5      90  -> 5
      80  -> 1      90  -> 5

done    - 1 order with 100 price, (may be also few orders with 110 price) + uinqueID order
partial - 1 order with price 110

```

### ProcessMarketOrder

```go
// ProcessMarketOrder immediately gets definite quantity from the order book with market price
// Arguments:
//      side     - what do you want to do (ob.Sell or ob.Buy)
//      quantity - how much quantity you want to sell or buy
//      * to create new decimal number you should use decimal.New() func
//        read more at https://github.com/shopspring/decimal
// Return:
//      error        - not nil if price is less or equal 0
//      done         - not nil if your market order produces ends of anoter orders, this order will add to
//                     the "done" slice
//      partial      - not nil if your order has done but top order is not fully done
//      partialQuantityProcessed - if partial order is not nil this result contains processed quatity from partial order
//      quantityLeft - more than zero if it is not enought orders to process all quantity
func (ob *OrderBook) ProcessMarketOrder(side Side, quantity decimal.Decimal) (done []*Order, partial *Order, quantityLeft decimal.Decimal, err error) { .. }
```

For example:
```
ProcessMarketOrder(ob.Sell, decimal.New(6, 0))

asks: 110 -> 5      110 -> 5
      100 -> 1      100 -> 1
--------------  ->  --------------
bids: 90  -> 5      80 -> 1
      80  -> 2

done         - 2 (or more orders)
partial      - 1 order with price 80
quantityLeft - 0

```

```
ProcessMarketOrder(ob.Buy, decimal.New(10, 0))

asks: 110 -> 5
      100 -> 1
--------------  ->  --------------
bids: 90  -> 5      90  -> 5
      80  -> 1      80  -> 1
                    
done         - 2 (or more orders)
partial      - nil
quantityLeft - 4

```

### CancelOrder

```go
// CancelOrder removes order with given ID from the order book
func (ob *OrderBook) CancelOrder(orderID string) *Order { ... }
```

```
CancelOrder("myUinqueID-Sell-1-with-100")

asks: 110 -> 5
      100 -> 1      110 -> 5
--------------  ->  --------------
bids: 90  -> 5      90  -> 5
      80  -> 1      80  -> 1
                    
done         - 2 (or more orders)
partial      - nil
quantityLeft - 4

```

## License

The MIT License (MIT)

See LICENSE and AUTHORS files


orderbook

QR code generator (ASCII & PNG) for SEPA payments

# QR code generator (ASCII & PNG) for SEPA payments

[![PkgGoDev](https://pkg.go.dev/badge/github.com/jovandeginste/payme)](https://pkg.go.dev/github.com/jovandeginste/payme)
[![Go Report Card](https://goreportcard.com/badge/github.com/jovandeginste/payme)](https://goreportcard.com/report/github.com/jovandeginste/payme)
[![Go Coverage](https://github.com/jovandeginste/payme/wiki/coverage.svg)](https://raw.githack.com/wiki/jovandeginste/payme/coverage.html)

## What is this?

This tool makes it easier for people (in Europe) to pay with bank transfers. It does not serve as a payment gateway or
anything similar. It does no payment verification at all, it simply provides the necessary payment information in a QR
code, which may be scanned by the person who wants to pay.

The QR code contains the information necessary for a bank transaction in the form of a [SEPA credit
transfer](https://epc-qr.eu/). It can be used to prefill the transaction form if your [banking app supports](#Support)
payment by QR code.

The process of generating the QR code is entirely local and offline. It can be printed in ASCII in the terminal, or
exported as a PNG for inclusion in eg. a web page or a mail.

One QR code can be used without limit, but will always contain the same payment information: amount, remittance message,
destination account. More than one person can scan the same code to pay the same amount (eg. split a bill with friends),
or one person can scan the code on a recurring base (eg. you pay your internet invoice every month and it's a fixed
price)

## Install

```bash
$ go install github.com/jovandeginste/payme@latest
```

Usage:

```bash
Generate SEPA payment QR code

Usage:
  payme [flags]

Flags:
      --amount float        Amount of the transaction
      --bic string          BIC of the beneficiary
      --character-set int   QR code character set (default 2)
      --debug               print debug output
      --file string         write code to file, leave empty for stdout
  -h, --help                help for payme
      --iban string         IBAN of the beneficiary
      --name string         Name of the beneficiary
      --output string       output type: png or stdout (default "stdout")
      --purpose string      Purpose of the transaction
      --remittance string   Remittance (message)
      --structured          Make the remittance (message) structured
      --qr-version int         QR code version (default 2)
```

You can set some default values in your ENV, eg.:

```bash
export PAYME_IBAN=DE71110220330123456789
export PAYME_NAME="Franz Mustermänn"
export PAYME_BIC=BHBLDEHHXXX
```

Generate QR code as text, print on the console:

```bash
$ payme \
  --name "Franz Mustermänn" \
  --iban "DE71110220330123456789" \
  --amount 12.3 \
  --remittance "RF18539007547034"
```

Generate QR code as png, save as file:

```bash
$ payme \
  --name "Franz Mustermänn" \
  --iban "DE71110220330123456789" \
  --amount 12.3 \
  --remittance "RF18539007547034" \
  --output png \
  --file QR.png
```

## Support

Please provide feedback if your banking app supports or does not support these QR codes.

The QR code is tested with the mobile apps of these banks:

### Belgium

| Bank    | Support                                    |
| ------- | ------------------------------------------ |
| Belfius | Yes                                        |
| Fortis  | Problems with characters in the remittance |
| KBC     | Yes                                        |

## References

- https://en.wikipedia.org/wiki/Single_Euro_Payments_Area
- https://en.wikipedia.org/wiki/EPC_QR_code
- https://epc-qr.eu/


payme

Terminal stock watcher and stock position tracker

<a href="https://github.com/achannarasappa/ticker/releases"><img src="https://img.shields.io/github/v/release/achannarasappa/ticker" alt="Latest Release"></a>
 <a href="https://github.com/achannarasappa/ticker/actions"><img src="https://github.com/achannarasappa/ticker/workflows/test/badge.svg" alt="Build Status"></a>
 <a href='https://coveralls.io/github/achannarasappa/ticker?branch=master'><img src='https://coveralls.io/repos/github/achannarasappa/ticker/badge.svg?branch=master' alt='Coverage Status' /></a>
 <a href='https://goreportcard.com/badge/github.com/achannarasappa/ticker'><img src='https://goreportcard.com/badge/github.com/achannarasappa/ticker' alt='Report Card' /></a>


<h1 align="center">Ticker</h2>

Terminal stock & crypto price watcher and position tracker


<img align="center" src="./docs/ticker.gif" />


## Features

* Live stock & crypto price quotes
* Track value of your stock positions
* Support for multiple cost basis lots
* Support for pre and post market price quotes

## Install

Download the pre-compiled binaries from the [releases page](https://github.com/achannarasappa/ticker/releases) and copy to a location in `PATH` or see quick installs below

**homebrew**
```
brew install achannarasappa/tap/ticker
```

**linux**
```sh
curl -Ls https://api.github.com/repos/achannarasappa/ticker/releases/latest \
| grep -wo "https.*linux-amd64*.tar.gz" \
| wget -qi - \
&& tar -xvf ticker*.tar.gz ticker \
&& chmod +x ./ticker \
&& sudo mv ticker /usr/local/bin/
```

**windows**
```
winget install -e --id achannarasappa.ticker
```

**docker**
```sh
docker run -it --rm achannarasappa/ticker
```

Note: config file can be mounted from the host machine by using a bind mount with `-v ~/.ticker.yaml:/.ticker.yaml`

**snap**
```sh
sudo snap install ticker
sudo snap connect ticker:ticker-config
```

Note: config file will need to be set with `--config $HOME/ticker.yaml` since Snap does not allow access to dotfiles

### Third-party repositories
These repositories are maintained by a third-party and may not have the latest versions available

**MacPorts**
```
sudo port selfupdate
sudo port install ticker
```

## Quick Start

```sh
ticker -w NET,AAPL,TSLA
```

## Usage
|Option Name|Alias|Flag|Default|Description|
|-------------------|--|-------------------|----------------|-------------------------------------------------|
| | |--config |`~/.ticker.yaml`|config file location with watchlist and positions|
|`interval` |-i|--interval |`5` |Refresh interval in seconds|
|`watchlist` |-w|--watchlist | |comma separated list of symbols to watch|
|`show-tags` | |--show-tags | |display currency, exchange name, and quote delay for each quote |
|`show-fundamentals`| |--show-fundamentals| |display open price, previous close, and day range |
|`show-separator` | |--show-separator | |layout with separators between each quote|
|`show-summary` | |--show-summary | |show total day change, total value, and total value change|
|`show-positions` | |--show-positions | |show positions including weight, average cost, and quantity|
|`sort` | |--sort | |sort quotes on the UI - options are change percent (default), `alpha`, `value`, and `user`|
|`version` | |--version | |print the current version number|
|`debug` | | | |enable debug logging to `./ticker-log-<date>.log`|

## Configuration

Configuration is not required to watch stock price but is helpful when always watching the same stocks. Configuration can also be used to set cost basis lots which will in turn be used to show total gain or loss on any position.

```yaml
# ~/.ticker.yaml
show-summary: true
show-tags: true
show-fundamentals: true
show-separator: true
show-positions: true
interval: 5
currency: USD
currency-summary-only: false
watchlist:
 - NET
 - TEAM
 - ESTC
 - BTC-USD # Bitcoin price via Yahoo
 - SOL.X # Solana price via Coinbase
 - BIT-30MAY25-CDE.CB # Bitcoin futures contract price via Coinbase
lots:
 - symbol: "ABNB"
 quantity: 35.0
 unit_cost: 146.00
 - symbol: "ARKW"
 quantity: 20.0
 unit_cost: 152.25
 - symbol: "ARKW"
 quantity: 20.0
 unit_cost: 145.35
 fixed_cost: 7.00 # e.g. brokerage commission fee
groups:
 - name: crypto
 watchlist:
 - SHIB-USD
 - VGX-USD
 lots:
 - symbol: SOL1-USD
 quantity: 17
 unit_cost: 159.10
```

* All properties in `.ticker.yaml` are optional
* Symbols not on the watchlist that exists in `lots` are implicitly added to the watchlist
* To add multiple cost basis lots (`quantity`, `unit_cost`) for the same `symbol`, include two or more entries - see `ARKW` example above
* `.ticker.yaml` can be set in user home directory, the current directory, or [XDG config home](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html)
* Quantities can be negative to represent closed positions (position netting), short positions, borrowed assets, and other concepts

### Display Options

With `--show-summary`, `--show-tags`, `--show-fundamentals`, `--show-positions`, and `--show-separator` options set, the layout and information displayed expands:

<img src="./docs/ticker-all-options.png" />

### Sorting

It's possible to set a custom sort order with the `--sort` flag or `sort:` config option with these options:

* Default - change percent with closed markets at the end
* `alpha` to sort alphabetically by symbol
* `value` to sort by position value
* `user` to sort by the order defined in configuration with positions on first then watched symbols

### Groups

Watchlists and lots can be grouped in `.ticker.yml` under the `groups` property. While running `ticker`, press <kbd>TAB</kbd> to cycle forward through groups or <kbd>SHIFT+TAB</kbd> to cycle backward.

* If top level `watchlist` or `lots` properties are defined in the configuration file, the entries there will be added to a group named `default` which will always be shown first
* Ordering is defined by order in the configuration file

### Data Sources & Symbols

`ticker` pulls market data from a few different sources with Yahoo Finance as the default. Symbols for non default data sources follow the format `<symbol>.<source>` where `<symbol>` is the canonical symbol within that data source and `<source>` is the data source specifier. Below is a list of the supported data sources and their specifiers:

* *none* - symbols with no suffix will default to Yahoo Finance as the data source
* `.X` - symbols with this suffix are shorthand symbols that are specific to ticker and intended to provide more concise and familiar symbols for popular assets (e.g. using `SOL.X` rather than `SOLANA.CG`)
 * The full list of ticker symbols can be found [here](https://github.com/achannarasappa/ticker-static/blob/master/symbols.csv). Initial values are populated with the top cryptocurrencies by volume on Coinbase at the time of update
* `.CB` - symbols with this suffix will use Coinbase as the data source. The symbol can be found by searching for the asset on [Coinbase](https://www.coinbase.com/explore/s/listed) and finding the symbol for the asset. (e.g. for Starknet check the [market page](https://www.coinbase.com/advanced-trade/spot/STRK-USD) to find the symbol `STRK` and set the symbol to `STRK.CB` in ticker).

Note: Coincap (`.CC`) and CoinGecko (`.CG`) are no longer supported after v5.0.0

### Currency Conversion

`ticker` supports converting from the exchange's currency to a local currency. This can be set by setting the `currency` property in `.ticker.yaml` to a [ISO 4217 3-digit currency code](https://docs.1010data.com/1010dataReferenceManual/DataTypesAndFormats/currencyUnitCodes.html).

<img src="./docs/ticker-currency.png" />

* When a `currency` is defined, all values are converted including summary, quote, and position
* Add cost basis lots in the currency of the exchange - these will be converted automatically when `currency` is defined
* If a `currency` is not set (default behavior) and the `show-summary` option is enabled, the summary will be calculated in USD regardless of the exchange currency to avoid mixing currencies
* Currencies are retrieved only once at start time - currency exchange rates do fluctuate over time and thus converted values may vary depending on when ticker is started
* If the `currency-summary-only` is set to `true` and a value is set for `currency`, only the summary values will be converted
* If `currency-disable-unit-cost-conversion` flag to `true`, currency conversion will not be done when calculating the cost basis. This can be useful for users that purchase a non-US asset and want to use the currency exchange rate at the time of purchase by inputting the unit cost in their local currency (set in `currency`) rather than using the most recent currency exchange rate.

### Custom Color Schemes

`ticker` supports setting custom color schemes from the config file. Colors are represented by a [hex triplet](https://en.wikipedia.org/wiki/Web_colors#Hex_triplet). Below is an annotated example config block from `.ticker.yaml` where custom colors are set:

```yaml
# ~/.ticker.yaml
watchlist:
 - NET
 - TEAM
 - ESTC
 - BTC-USD
colors:
 text: "#005fff"
 text-light: "#0087ff"
 text-label: "#00d7ff"
 text-line: "#00ffff"
 text-tag: "#005fff"
 background-tag: "#0087ff"
```

* Terminals supporting TrueColor will be able to represent the full color space and in other cases colors will be down sampled
* Any omitted or invalid colors will revert to default color scheme values

### Printing Positions

`ticker` supports printing positions to the terminal as text by using `ticker print`. Output defaults to JSON but CSV output can also be generated by passing the `--format=csv` flag.

```sh
$ ticker --config=./.ticker.yaml print
[{"name":"Airbnb, Inc.","symbol":"ABNB","price":164.71,"value":16965.13,"cost":15038,"quantity":103,"weight":53.66651978212161},{"name":"Tesla, Inc.","symbol":"TSLA","price":732.35,"value":14647,"cost":15660,"quantity":20,"weight":46.33348021787839}]
```

* Ensure there is at least one lot in the configuration file in order to generate output
* A specific config file can be specified with the `--config` flag

## Notes

* **Market data delay**
 * _Yahoo Finance_ - Market data pulled from Yahoo finance will have some lag (<~30s) introduced by intermediary systems and certain exchanges will impose intentional delays on data. NYSE and NASDAQ offer real-time market data but other exchanges may not. Consult the [help article](https://help.yahoo.com/kb/SLN2310.html) on exchange delays to determine which exchanges you can expect delays for or use the `--show-tags` flag to include timeliness of data alongside quotes in `ticker`. Yahoo Finance also relies on polling which introduces some delay (>=5s). `refresh-interval` determines the polling frequency.
 * _Coinbase_ - Market data for spot assets on Coinbase is directly streamed from the exchange through a WebSocket connection and is available in near real-time. Derivatives assets (i.e. symbols with `-CDE` suffix) are polling based however Basis is updated in near real-time based on spot market data changes
* **Non-US Symbols, Forex, ETFs** - The names for there may differ from their common name/symbols. Try searching the native name in [Yahoo finance](https://finance.yahoo.com/) to determine the symbol to use in `ticker`
* **Terminal fonts** - Font with support for the [`HORIZONTAL LINE SEPARATOR` unicode character](https://www.fileformat.info/info/unicode/char/23af/fontsupport.htm) is required to properly render separators (`--show-separator` option)

## Integrations

* [alpaca-ticker-config](https://www.npmjs.com/package/alpaca-ticker-config) - Pull [alpaca.markets](https://alpaca.markets) positions into `.ticker.yaml` from the command line

## Development

Running tests:
```sh
go run github.com/onsi/ginkgo/v2/ginkgo -cover ./...
```

Linting:
```sh
golangci-lint run
```

## Libraries `ticker` uses

* [bubbletea](https://github.com/charmbracelet/bubbletea) - terminal UI framework
* [termenv](https://github.com/muesli/termenv) - color and styling for the terminal
* [term-grid](https://github.com/achannarasappa/term-grid) - grid layout library terminal UIs

## Related Tools

* [tickrs](https://github.com/tarkah/tickrs) - real-time terminal stock ticker with support for graphing, options, and other analysis information
* [cointop](https://github.com/miguelmota/cointop) - terminal UI tracking cryptocurrencies

ticker

One unified interface for multiple Payment Service Providers (PsP) to process online payment.

# Sleet

[![CircleCI status](https://circleci.com/gh/BoltApp/sleet.png?circle-token=d60ceb64eb6ebdfd6a45a4703563c1752598db63 "CircleCI status")](https://circleci.com/gh/BoltApp/sleet)
[![GoDoc](https://godoc.org/github.com/BoltApp/sleet?status.svg)](https://pkg.go.dev/github.com/BoltApp/sleet?tab=doc)
[![Go Report Card](https://goreportcard.com/badge/github.com/BoltApp/sleet)](https://goreportcard.com/report/github.com/BoltApp/sleet)

Payment abstraction library - interact with different Payment Service Providers (PsP) with one unified interface.

## Installation

`go get github.com/BoltApp/sleet`

## Methodology

Wherever possible, we try to use native Golang implementations of the PsP's API. We also assume that the caller can pass along raw credit card information (i.e. are PCI compliant)

### Supported Gateway API Calls

1. Authorize
2. Capture
3. Void
4. Refund

### Webhooks Support

We support abstracting PsP Webhook notifications into a common interface. 

### PsP Support Matrix
| PsP | Gateway APIs | Webhooks |
|-----|--------------|----------|
| [Adyen](https://docs.adyen.com/classic-integration/api-integration-ecommerce) | ✅ | ❌ |
| [Authorize.Net](https://developer.authorize.net/api/reference/index.html#payment-transactions) | ✅ | ❌ |
| [Braintree](https://www.braintreepayments.com/) | ✅ | ❌ |
| [CyberSource](https://developer.cybersource.com/api-reference-assets/index.html#payments) | ✅ | ❌ |
| [Checkout.com](https://api-reference.checkout.com/) | ✅ | ❌ |
| [FirstData](https://docs.firstdata.com/org/gateway/docs/api) | ✅ | ❌ |
| [NMI](https://secure.networkmerchants.com/gw/merchants/resources/integration/integration_portal.php#methodology) | ✅ | ❌ |
| [Orbital](https://developer.jpmorgan.com/products/orbital-api) | ✅ | ❌ |
| [RocketGate](https://www.rocketgate.com/) | ✅ | ❌ |
| [Stripe](https://stripe.com/docs/api) | ✅ | ❌ |

## To run tests

###  Unit test

```
go test -v -tags=unit $(go list ./... | grep -v integration-tests)
```

### Integration test
The following environment variables are needed in order to run tests

```shell script
$ export ADYEN_USERNAME="YOUR_ADYEN_WEBSERVICE_USERNAME"
$ export ADYEN_ACCOUNT="YOUR_ADYEN_MERCHANT_ACCOUNT"
$ export ADYEN_PASSWORD="YOUR_ADYEN_WEBSERVICE_PASSWORD"
$ export STRIPE_TEST_KEY="YOUR_STRIPE_API_KEY"
$ export AUTH_NET_LOGIN_ID="YOUR_AUTHNET_LOGIN"
$ export AUTH_NET_TXN_KEY="YOUR_AUTHNET_TXN_KEY"
$ export BRAINTREE_MERCHANT_ID="YOUR_BRAINTREE_MERCHANT_ACCOUNT"
$ export BRAINTREE_PUBLIC_KEY="YOUR_BRAINTREE_PUBLIC_KEY"
$ export BRAINTREE_PRIVATE_ID="YOUR_BRAINTREE_PRIVATE_KEY"
$ export CYBERSOURCE_ACCOUNT="YOUR_CYBS_ACCOUNT"
$ export CYBERSOURCE_API_KEY="YOUR_CYBS_KEY"
$ export CYBERSOURCE_SHARED_SECRET="YOUR_CYBS_SECRET"
$ export NMI_SECURITY_KEY="YOUR_NMI_PRIVATE_KEY"
$ export CHECKOUTCOM_TEST_KEY="YOUR_CHECKOUTCOM_PRIVATE_KEY"
$ export CHECKOUTCOM_TEST_KEY_WITH_PCID="YOUR_CHECKOUTCOM_PRIVATE_KEY_WITH_PROCESSING_CHANNEL_ID"
$ export CHECKOUTCOM_TEST_PCID="YOUR_CHECKOUTCOM_PROCESSING_CHANNEL_ID"
```

Then run tests with: `go test ./integration-tests/`

## Code Example for Auth + Capture

```go
import (
  "github.com/BoltApp/sleet"
  "github.com/BoltApp/sleet/gateways/authorize_net"
)
// Generate a client using your own credentials
client := authorize_net.NewClient("AUTH_NET_LOGIN_ID", "AUTH_NET_TXN_KEY")

amount := sleet.Amount{
  Amount: 100,
  Currency: "USD",
}
card := sleet.CreditCard{
  FirstName: "Bolt",
  LastName: "Checkout",
  Number: "4111111111111111",
  ExpMonth: 8,
  EpxYear: 2010,
  CVV: "000",
}
streetAddress := "22 Linda St."
locality := "Hoboken"
regionCode := "NJ"
postalCode := "07030"
countryCode := "US"
address := sleet.BillingAddress{
  StreetAddress1: &streetAddress,
  Locality:       &locality,
  RegionCode:     &regionCode,
  PostalCode:     &postalCode,
  CountryCode:    &countryCode,
}
// To get specific response headers, add them to the request options.
// They will be attached to the AuthorizationResponse
options := make(map[string]interface{})
options["ResponseHeader"] = []string{"x-test-header"}
authorizeRequest := sleet.AuthorizationRequest{
  Amount: &amount,
  CreditCard: &card,
  BillingAddress: &address,
  Options: options,
}
authorizeResponse, _ := client.Authorize(&authorizeRequest)

captureRequest := sleet.CaptureRequest{
  Amount:               &amount,
  TransactionReference: authorizeResponse.TransactionReference,
}
client.Capture(&captureRequest)
```


sleet

Embedded transactional database of accounts, running in multithreaded mode

# transaction

[![Build Status](https://travis-ci.org/claygod/transaction.svg?branch=master)](https://travis-ci.org/claygod/transaction)
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge-flat.svg)](https://github.com/avelino/awesome-go)
[![API documentation](https://godoc.org/github.com/claygod/transaction?status.svg)](https://godoc.org/github.com/claygod/transaction)
[![Go Report Card](https://goreportcard.com/badge/github.com/claygod/transaction)](https://goreportcard.com/report/github.com/claygod/transaction)

Embedded transactional database of accounts, running in multithreaded mode. Coverage 92.8%

The library operates only with integers. If you want to work with hundredths (for example, cents in dollars), multiply everything by 100. For example, a dollar and a half, it will be 150.
Limit on the maximum account size: 2 to 63 degrees (9,223,372,036,854,775,807). For example: on the account cannot be more than $92,233,720,368,547,758.07

The library works in parallel mode and can process millions of requests per second.
Parallel requests to the same account should not lead to an erroneous change in the balance of this account.
Debit and credit with the account can be done ONLY as part of the transaction.

The library has two main entities: a unit and an account.

### Unit

- A unit can be a customer, a company, etc.
- A unit can have many accounts (accounts are called a string variable)
- A unit cannot be deleted if at least one of its accounts is not zero
- If a unit receives a certain amount for a nonexistent account, such an account will be created

### Account

- The account serves to account for money, shares, etc.
- The account necessarily belongs to any unit.
- The account belongs to only one unit.
- There is only one balance on one account.
- Balance is calculated only in whole numbers.

## Usage

Important: in the description of methods all error return codes are written.
Descriptions in the documentation: https://godoc.org/github.com/claygod/transaction
The transaction has no limits on the number of credits and debits.

### Create / delete

```go
tr := transaction.New()
tr.Start()
tr.AddUnit(123)
tr.DelUnit(123)
```	

### Credit/debit of an account

Credit and debit operations with the account:

```go
t.Begin().Credit(id, "USD", 1).End()
```	

```go
t.Begin().Debit(id, "USD", 1).End()
```

### Transfer

Example of transfer of one dollar from one account to another.

```go
t.Begin().
	Credit(idFrom, "USD", 1).
	Debit(idTo, "USD", 1).
	End()
```

### Purchase / Sale

A purchase is essentially two simultaneous funds transfers

```go
// Example of buying two shares of "Apple" for $10
tr.Begin().
	Credit(buyerId, "USD", 10).Debit(sellerId, "USD", 10).
	Credit(sellerId, "APPLE", 2).Debit(buyerId, "APPLE", 2).
	End()
```

### Save / Load

```go
// Save
	tr := New()
	tr.Start()
	tr.AddUnit(123)
	tr.Begin().Debit(123, "USD", 7).End()
	tr.Save(path)
	...
```

```go
// Load
	tr := New()
	tr.Start()
	tr.Load(path)
	tr.Begin().Credit(123, "USD", 7).End()
	...
```

### Example

```go
package main

import (
	"fmt"

	tn "github.com/claygod/transaction"
)

func main() {
	tr := tn.New()
	tr.Start()

	// add unit
	switch res := tr.AddUnit(123); res {
	case tn.Ok:
		fmt.Println("Done! Unit created")
	case tn.ErrCodeCoreCatch:
		fmt.Println("Not obtained permission")
	case tn.ErrCodeUnitExist:
		fmt.Println("Such a unit already exists")
	default:
		fmt.Println("Unknown error")
	}

	// transaction
	switch res := tr.Begin().Debit(123, "USD", 5).End(); res {
	case tn.Ok:
		fmt.Println("Done! Money added")
	case tn.ErrCodeUnitNotExist:
		fmt.Println("Unit not exist")
	case tn.ErrCodeTransactionCatch:
		fmt.Println("Account not catch")
	case tn.ErrCodeTransactionDebit:
		fmt.Println("Such a unit already exists")
	default:
		fmt.Println("Unknown error")
	}

	// save
	switch res := tr.Save("./test.tdb"); res {
	case tn.Ok:
		fmt.Println("Done! Data saved to file")
	case tn.ErrCodeCoreStop:
		fmt.Println("Unable to stop app")
	case tn.ErrCodeSaveCreateFile:
		fmt.Println("Could not create file")
	default:
		fmt.Println("Unknown error")
	}

	// del unit (There will be an error!)
	switch _, res := tr.DelUnit(123); res {
	case tn.Ok:
		fmt.Println("Done!")
	case tn.ErrCodeCoreCatch:
		fmt.Println("Not obtained permission")
	case tn.ErrCodeUnitExist:
		fmt.Println("There is no such unit")
	case tn.ErrCodeAccountNotStop:
		fmt.Println("Accounts failed to stop")
	case tn.ErrCodeUnitNotEmpty:
		fmt.Println("Accounts are not zero! You must withdraw money from the account")
	default:
		fmt.Println("Unknown error")
	}

	// transaction
	switch res := tr.Begin().Credit(123, "USD", 5).End(); res {
	case tn.Ok:
		fmt.Println("Done! Account cleared")
	case tn.ErrCodeUnitNotExist:
		fmt.Println("Unit not exist")
	case tn.ErrCodeTransactionCatch:
		fmt.Println("Account not catch")
	case tn.ErrCodeTransactionCredit:
		fmt.Println("Such a unit already exists")
	default:
		fmt.Println("Unknown error")
	}

	// del unit (Now it will work out!)
	switch _, res := tr.DelUnit(123); res {
	case tn.Ok:
		fmt.Println("Done! Now the account has been deleted")
	case tn.ErrCodeCoreCatch:
		fmt.Println("Not obtained permission")
	case tn.ErrCodeUnitNotExist:
		fmt.Println("There is no such unit")
	case tn.ErrCodeAccountNotStop:
		fmt.Println("Accounts failed to stop")
	case tn.ErrCodeUnitNotEmpty:
		fmt.Println("Accounts are not zero")
	default:
		fmt.Println(res)
	}
}
```

Output:

```
Done! Unit created
Done! Money added
Done! Data saved to file
Accounts are not zero! You must withdraw money from the account
Done! Account cleared
Done! Now the account has been deleted
```

## Sequence diagram

![Sequence diagram](./diagram.png)

## API

- New
- Load ("path")
- Start ()
- AddUnit(ID)
- Begin().Debit(ID, key, amount).End()
- Begin().Credit(ID, key, amount).End()
- TotalUnit(ID)
- TotalAccount(ID, key)
- DelUnit(ID)
- Stop ()
- Save ("path")

## F.A.Q.

Why can not I add or withdraw funds from the account without a transaction, because it's faster?
- The user should not be able to make a transaction on his own. This reduces the risk. In addition, in the world of finance, single operations are rare.

Does the performance of your library depend on the number of processor cores?
- Depends on the processor (cache size, number of cores, frequency, generation), and also depends on the RAM (size and speed), the number of accounts, the type of disk (HDD / SSD) when saving and loading.

I have a single-core processor, should I use your library in this case?
- The performance of the library is very high, so it will not be a break in your application. However, the system block is better to upgrade ;-)


## ToDo

- [x] Draw a sequence diagram
- [ ] Example of using a library as a server
- [ ] Write-Ahead Logging (WAL)

## Bench

i7-6700T:

- BenchmarkTotalUnitSequence-8 	 3000000	 419 ns/op
- BenchmarkTotalUnitParallel-8 	10000000	 185 ns/op
- BenchmarkCreditSequence-8 	 5000000	 311 ns/op
- BenchmarkCreditParallel-8 	10000000	 175 ns/op
- BenchmarkDebitSequence-8 	 5000000	 314 ns/op
- BenchmarkDebitParallel-8 	10000000	 178 ns/op
- BenchmarkTransferSequence-8 	 3000000	 417 ns/op
- BenchmarkTransferParallel-8 	 5000000	 277 ns/op
- BenchmarkBuySequence-8 	 2000000	 644 ns/op
- BenchmarkBuyParallel-8 	 5000000	 354 ns/op

## Give us a star!

If you like or are using this project to learn or start your solution, please give it a star. Thank you!

#### Copyright © 2017-2025 Eduard Sesigin. All rights reserved. Contacts: <claygod@yandex.ru>

transaction

Library of financial functions for time value of money (annuities), cash flow, interest rate conversions, bonds and depreciation calculations

# go-finance [![GoDoc](https://godoc.org/github.com/alpeb/go-finance?status.svg)](https://godoc.org/github.com/alpeb/go-finance/fin) [![Go Report Card](https://goreportcard.com/badge/github.com/alpeb/go-finance)](https://goreportcard.com/report/github.com/alpeb/go-finance)
Go library containing a collection of financial functions for time value of money (annuities), cash flow, interest rate conversions, bonds and depreciation calculations.

## List of functions

### Rates

- [EffectiveRate](https://godoc.org/github.com/alpeb/go-finance/fin#EffectiveRate)
- [NominalRate](https://godoc.org/github.com/alpeb/go-finance/fin#NominalRate)

### Cashflow

- [NetPresentValue](https://godoc.org/github.com/alpeb/go-finance/fin#NetPresentValue)
- [InternalRateOfReturn](https://godoc.org/github.com/alpeb/go-finance/fin#InternalRateOfReturn)
- [ModifiedInternalRateOfReturn](https://godoc.org/github.com/alpeb/go-finance/fin#ModifiedInternalRateOfReturn)
- [ScheduledNetPresentValue](https://godoc.org/github.com/alpeb/go-finance/fin#ScheduledNetPresentValue)
- [ScheduledInternalRateOfReturn](https://godoc.org/github.com/alpeb/go-finance/fin#ScheduledInternalRateOfReturn)

### TVM

- [PresentValue](https://godoc.org/github.com/alpeb/go-finance/fin#PresentValue)
- [FutureValue](https://godoc.org/github.com/alpeb/go-finance/fin#FutureValue)
- [Payment](https://godoc.org/github.com/alpeb/go-finance/fin#Payment)
- [Periods](https://godoc.org/github.com/alpeb/go-finance/fin#Periods)
- [Rate](https://godoc.org/github.com/alpeb/go-finance/fin#Rate)
- [InterestPayment](https://godoc.org/github.com/alpeb/go-finance/fin#InterestPayment)
- [PrincipalPayment](https://godoc.org/github.com/alpeb/go-finance/fin#PrincipalPayment)

### Bonds

- [DaysDifference](https://godoc.org/github.com/alpeb/go-finance/fin#DaysDifference)
- [DaysPerYear](https://godoc.org/github.com/alpeb/go-finance/fin#DaysPerYear)
- [TBillEquivalentYield](https://godoc.org/github.com/alpeb/go-finance/fin#TBillEquivalentYield)
- [TBillPrice](https://godoc.org/github.com/alpeb/go-finance/fin#TBillPrice)
- [TBillYield](https://godoc.org/github.com/alpeb/go-finance/fin#TBillYield)
- [DiscountRate](https://godoc.org/github.com/alpeb/go-finance/fin#DiscountRate)
- [PriceDiscount](https://godoc.org/github.com/alpeb/go-finance/fin#PriceDiscount)

### Depreciation

- [DepreciationFixedDeclining](https://godoc.org/github.com/alpeb/go-finance/fin#DepreciationFixedDeclining)
- [DepreciationSYD](https://godoc.org/github.com/alpeb/go-finance/fin#DepreciationSYD)
- [DepreciationStraightLine](https://godoc.org/github.com/alpeb/go-finance/fin#DepreciationStraightLine)

## Docs

Checkout the full [docs](https://godoc.org/github.com/alpeb/go-finance/fin).

Also check this excellent blog post [Learning finance concepts using
go-finance](https://blog.aawadia.dev/2020/11/30/finance-concepts-go-finance/)
for some examples and a general intro.

## License

[Mozilla Public License 2.0](https://github.com/alpeb/go-finance/blob/master/LICENSE)


go-finance

Module to fetch exchange rates, check VAT numbers via VIES and check IBAN bank account numbers

# go-finance

[![Go Report Card](https://goreportcard.com/badge/github.com/pieterclaerhout/go-finance)](https://goreportcard.com/report/github.com/pieterclaerhout/go-finance)
[![Documentation](https://godoc.org/github.com/pieterclaerhout/go-finance?status.svg)](http://godoc.org/github.com/pieterclaerhout/go-finance)
[![license](https://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://github.com/pieterclaerhout/go-finance/raw/master/LICENSE)
[![GitHub version](https://badge.fury.io/gh/pieterclaerhout%2Fgo-finance.svg)](https://badge.fury.io/gh/pieterclaerhout%2Fgo-finance)
[![GitHub issues](https://img.shields.io/github/issues/pieterclaerhout/go-finance.svg)](https://github.com/pieterclaerhout/go-finance/issues)

This is a [Golang](https://golang.org) library which contains finance related functions.

## Exchange Rates

The following example explains how to use this package to retrieve the exchange rates from [ECB](https://www.ecb.europa.eu):

```go
package main

import (
	"fmt"
	"os"

	"github.com/pieterclaerhout/go-finance"
)

func main() {

	rates, err := finance.ExchangeRates()
	if err != nil {
		fmt.Println("ERROR:", err.Error())
		os.Exit(1)
	}

	for currency, rate := range rates {
		fmt.Println(currency, "-> €1 =", rate)
	}

}
```

## Checking VAT Numbers


You can also VAT numbers via the [VIES service](http://ec.europa.eu/taxation_customs/vies/vatRequest.html). The following sample code shows how to do this:


```go
package main

import (
	"fmt"
	"os"

	"github.com/pieterclaerhout/go-finance"
)

func main() {

	info, err := finance.CheckVAT("BE0836157420")
	if err != nil {
		fmt.Println("ERROR:", err.Error())
		os.Exit(1)
	}

	fmt.Println(info)

}
```

## IBAN & BIC

There is also a function which converts a regular Belgian Bank Account Number to it's IBAN / BIC equivalent:

```go
package main

import (
	"fmt"
	"os"

	"github.com/pieterclaerhout/go-finance"
)

func main() {

	info, err := finance.CheckIBAN("738120256174")
	if err != nil {
		fmt.Println("ERROR:", err.Error())
		os.Exit(1)
	}

	fmt.Println(info)

}
```

Technical analysis library with advanced market analysis and trading strategies

## Techan
![](https://travis-ci.org/sdcoffey/techan.svg?branch=master)

[![codecov](https://codecov.io/gh/sdcoffey/techan/branch/master/graph/badge.svg)](https://codecov.io/gh/sdcoffey/techan)

TechAn is a **tech**nical **an**alysis library for Go! It provides a suite of tools and frameworks to analyze financial data and make trading decisions.

## Features 
* Basic and advanced technical analysis indicators
* Profit and trade analysis
* Strategy building

### Installation
```sh
$ go get github.com/sdcoffey/techan
```

### Quickstart
```go
series := techan.NewTimeSeries()

// fetch this from your preferred exchange
dataset := [][]string{
	// Timestamp, Open, Close, High, Low, volume
	{"1234567", "1", "2", "3", "5", "6"},
}

for _, datum := range dataset {
	start, _ := strconv.ParseInt(datum[0], 10, 64)
	period := techan.NewTimePeriod(time.Unix(start, 0), time.Hour*24)

	candle := techan.NewCandle(period)
	candle.OpenPrice = big.NewFromString(datum[1])
	candle.ClosePrice = big.NewFromString(datum[2])
	candle.MaxPrice = big.NewFromString(datum[3])
	candle.MinPrice = big.NewFromString(datum[4])

	series.AddCandle(candle)
}

closePrices := techan.NewClosePriceIndicator(series)
movingAverage := techan.NewEMAIndicator(closePrices, 10) // Create an exponential moving average with a window of 10

fmt.Println(movingAverage.Calculate(0).FormattedString(2))
```

### Creating trading strategies
```go
indicator := techan.NewClosePriceIndicator(series)

// record trades on this object
record := techan.NewTradingRecord()

entryConstant := techan.NewConstantIndicator(30)
exitConstant := techan.NewConstantIndicator(10)

// Is satisfied when the price ema moves above 30 and the current position is new
entryRule := techan.And(
	techan.NewCrossUpIndicatorRule(entryConstant, indicator),
	techan.PositionNewRule{})
	
// Is satisfied when the price ema moves below 10 and the current position is open
exitRule := techan.And(
	techan.NewCrossDownIndicatorRule(indicator, exitConstant),
	techan.PositionOpenRule{})

strategy := techan.RuleStrategy{
	UnstablePeriod: 10, // Period before which ShouldEnter and ShouldExit will always return false
	EntryRule:      entryRule,
	ExitRule:       exitRule,
}

strategy.ShouldEnter(0, record) // returns false
```

### Enjoying this project?
Are you using techan in production? You can sponsor its development by buying me a coffee! ☕

**ETH:** `0x2D9d3A1c16F118A3a59d0e446d574e1F01F62949`

### Credits
Techan is heavily influenced by the great [ta4j](https://github.com/ta4j/ta4j). Many of the ideas and frameworks in this library owe their genesis to the great work done over there.

### License

Techan is released under the MIT license. See [LICENSE](./LICENSE) for details.


techan

Package vat
===

[![Go Report Card](https://goreportcard.com/badge/github.com/dannyvankooten/vat)](https://goreportcard.com/report/github.com/dannyvankooten/vat)
[![GoDoc](https://godoc.org/github.com/dannyvankooten/vat?status.svg)](https://godoc.org/github.com/dannyvankooten/vat)
[![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/dannyvankooten/vat/master/LICENSE)

Package for validating VAT numbers & retrieving VAT rates (from [ibericode/vat-rates](https://github.com/ibericode/vat-rates)) in Go.

## Installation

Use go get.

```
go get github.com/dannyvankooten/vat
```

Then import the package into your own code.

```
import "github.com/dannyvankooten/vat"
```

## Usage

### Validating VAT numbers

VAT numbers can be validated by format, existence or both. VAT numbers are looked up using the [VIES VAT validation API](http://ec.europa.eu/taxation_customs/vies/).

```go
package main

import "github.com/dannyvankooten/vat"

func main() {
  // Validate number by format + existence
  validity, err := vat.ValidateNumber("NL123456789B01")

  // Validate number format
  validity, err := vat.ValidateNumberFormat("NL123456789B01")

  // Validate number existence
  validity, err := vat.ValidateNumberExistence("NL123456789B01")
}
```

### Retrieving VAT rates

> This package relies on a [community maintained repository of vat rates](https://github.com/ibericode/vat-rates). We invite you to toggle notifications for that repository and contribute changes to VAT rates in your country once they are announced.

To get VAT rate periods for a country, first get a CountryRates struct using the country's ISO-3166-1-alpha2 code.

You can get the rate that is currently in effect using the `GetRate` function.

```go
package main

import (
  "fmt"
  "github.com/dannyvankooten/vat"
)

func main() {
  c, err := vat.GetCountryRates("NL")
  r, err := c.GetRate("standard")

  fmt.Printf("Standard VAT rate for NL is %.2f", r)
  // Output: Standard VAT rate for NL is 21.00
}
```

## License

MIT licensed. See the LICENSE file for details.


High performance 128-bit fixed-point decimal numbers

# dec128

[![Go Reference](https://pkg.go.dev/badge/github.com/jokruger/dec128.svg)](https://pkg.go.dev/github.com/jokruger/dec128)
[![Go Report Card](https://goreportcard.com/badge/github.com/jokruger/dec128)](https://goreportcard.com/report/github.com/jokruger/dec128)
[![codecov](https://codecov.io/gh/jokruger/dec128/graph/badge.svg?token=TQWE8PA4AN)](https://codecov.io/gh/jokruger/dec128)
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go)

High performance 128-bit fixed-point decimal numbers in go.

## Key Objectives / Features

- [x] High performance
- [x] Zero dependencies
- [x] Minimal or zero memory allocation
- [x] Scale up to 19 decimal places
- [x] Fixed size memory layout (128 bits)
- [x] No panic or error arithmetics (use NaN instead)
- [x] Immutability (methods return new instances)
- [x] Basic arithmetic operations required for financial calculations (specifically for banking and accounting)
- [ ] Additional arithmetic operations for scientific calculations
- [x] Easy to use
- [x] Easy to integrate with external systems (e.g. databases, accounting systems, JSON, etc.)
- [x] Financially correct rounding
- [x] Correct comparison of numbers encoded in different scales (e.g. 1.0 == 1.00)
- [x] Correct handling of NaN values (e.g. NaN + 1 = NaN)
- [x] Conversion to canonical representation (e.g. 1.0000 -> 1)
- [x] Conversion to fixed string representation (e.g. 1.0000 -> "1.0000")
- [x] Conversion to human-readable string representation (e.g. 1.0000 -> "1")

## Install

Run `go get github.com/jokruger/dec128`

## Requirements

This library requires Go version `>=1.23`

## Documentation

http://godoc.org/github.com/jokruger/dec128

## Usage

```go
package main

import (
    "fmt"
    "github.com/jokruger/dec128"
)

func main() {
    principal := dec128.FromString("1000.00")
    annualRate := dec128.FromString("5.0")
    days := 30

    dailyRate := annualRate.Div(dec128.FromInt64(365))
    dailyRate = dailyRate.Div(dec128.FromInt64(100))

    accruedInterest := principal.Mul(dailyRate).Mul(dec128.FromInt64(days)).RoundBank(2)

    fmt.Printf("Principal: %v\n", principal.StringFixed())
    fmt.Printf("Annual Interest Rate: %v\n", annualRate.String())
    fmt.Printf("Days: %v\n", days)
    fmt.Printf("Accrued Interest: %v\n", accruedInterest.String())

    total := principal.Add(accruedInterest).RoundBank(2)
    fmt.Printf("Total after %v days: %v\n", days, total.StringFixed())
}
```

## Why not use other libraries?

There are several other libraries that provide decimal arithmetic in Go. However, most of them are either too slow, too memory-intensive, or lack the integration features required for financial applications. This library aims to provide a high-performance, low-memory, and easy-to-use alternative to existing libraries.

## Benchmarks

The following benchmarks were run on a MacBook Pro (2019) with a 2.6 GHz 6-Core Intel Core i7 processor and 16 GB of RAM (https://github.com/jokruger/go-decimal-benchmark).

```
                                 parse (ns/op)  string (ns/op)     add (ns/op)     mul (ns/op)     div (ns/op)

dec128.Dec128                           14.024          33.683           9.975           6.569          35.116
udecimal.Decimal                        23.302          41.854          12.226          11.346          40.877
alpacadecimal.Decimal                   89.528          78.884         206.393          60.364         451.828
shopspring.Decimal                     152.263         169.300         218.909          65.241         428.002
```

## Notes on Terminology

- **Scale**: Number of digits after the decimal point. For example, 1.00 has scale of 2 and 1.0000 has scale of 4.
- **Exponent**: Same as scale, but in the context of low-level implementation details or Dec128 encoding.
- **Canonical**: The representation of a number with the minimum number of decimal places required to represent the number.
- **Quantum\***: The smallest step at a given scale. For example, scale 2 has quantum 0.01

## License

This project is licensed under the MIT License. See the `LICENSE` file for details.

### Attribution

This project includes code derived from:

- A project licensed under the BSD 3-Clause License (Copyright © 2025 Quang).
- A project licensed under the MIT License (Copyright © 2019 Luke Champine).

See the `LICENSE` file for full license texts.


dec128

High performant & accurate currency computation package

<img src="https://user-images.githubusercontent.com/1092882/84137258-11328400-aa6a-11ea-94d9-9d58e56a0ea3.png" alt="webgo gopher" width="256px"/>

[![](https://github.com/naughtygopher/currency/actions/workflows/go.yml/badge.svg?branch=master)](https://github.com/naughtygopher/currency/actions)
[![Go Reference](https://pkg.go.dev/badge/github.com/naughtygopher/currency.svg)](https://pkg.go.dev/github.com/naughtygopher/currency)
[![Go Report Card](https://goreportcard.com/badge/github.com/naughtygopher/currency)](https://goreportcard.com/report/github.com/naughtygopher/currency)
[![Coverage Status](https://coveralls.io/repos/github/naughtygopher/currency/badge.svg?branch=master)](https://coveralls.io/github/naughtygopher/currency?branch=master)
[![Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go/tree/main?tab=readme-ov-file#financial)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/creativecreature/sturdyc/blob/master/LICENSE)

## Currency v2.0.1

Currency package helps you do currency computations accurately. `Currency` struct holds all the data required to define a currency.

```golang
type Currency struct {
	// Code represents the international currency code
	Code string
	// Symbol is the respective currency symbol
	Symbol string
	// Main represents the main value of the currency
	Main int
	// Fractional represents the fractional/sub unit of the currency
	Fractional uint
	// FUName is the name of the fractional/sub unit of the currency. e.g. paise
	FUName string
	// FUShare represents the no.of fractional/sub units that make up 1 main unit. e.g. ₹1 = 100 paise
	// Number of fractional units that make up 1 unit of the main value
	FUShare uint
	// PrefixSymbol if true will prefix the symbol when stringified
	PrefixSymbol bool
	// SuffixSymbol if true will suffix the symbol when stringified
	SuffixSymbol bool
}
```

### New(main int, fractional int, code, symbol string, funame string, fushare uint)

New returns a pointer of currency instance created based on the configuration.

```
main - Main/Super unit of the currency
fractional - Subunit/fractional unit of the currency
code - is the currency code according to [ISO 4217 specification](https://en.wikipedia.org/wiki/ISO_4217)
symbol - Unicode symbol of the currency
funame - Name of the fractional/sub unit
fushare - Number of fractional/sub units that make up 1 unit of the main/super unit
```

_IMPORTANT! Fractional unit can be negative only when the main value is 0. If the main value is not 0, fractional unit's negative sign is ignored._

### Parsers & convenience methods

1. `NewFractional(fractional int, symbol string, fulabel string, fushare uint)` returns a currency struct instance, given a currency's total value represented by the fractional unit
2. `ParseString(value string, code, symbol string, fulabel string, fushare uint)` returns a currency struct instance, given a currency value represented as string
3. `ParseFloat64(value float64, code, symbol string, funame string, fushare uint)` returns a currency struct instance, given a currency value represented in float64

### Computational methods

IMPORTANT: Computation is supported only between same type of currencies (i.e. currency codes _*must*_ match)

1. `c1.Add(c2 currency)` add c2 to c1, and update c1
2. `c1.AddInt(main int, fractional int)` add the currency equivalent of the main & fractional int to c1
3. `c1.Subtract(c2 currency)` subtract c2 from c1, and update c1
4. `c1.SubtractIn(main int, fractional int)` subtract the currency equivalent of the main & fractional int from c1
5. `c1.Multiply(n int)` multiply c1 by n, where n is an integer
6. `c1.MultiplyFloat64(n float64)` multiply c1 by n, where n is a float64 value
7. `c1.UpdateWithFractional(ftotal int)` would update the the value of c1, where _ftotal_ is the total value of the currency in fractional unit. e.g. INR, `UpdateWithFractional(100)` would set the main value as `1` and fractional unit as `0`
8. `c1.FractionalTotal() int` returns the total value of the currency in its fractional unit. e.g. INR, if the Main value is `1` and fractional unit is `0`, it would return `100`, i.e. 100 paise
9. `c1.Percent(n float64) currency` returns a new currency instance which is n percentage of c1
10. `c1.Allocate(n int, retain bool)[]currency, ok ` returns a slice of currency of size n. `ok` if **true** means the currency value is fully divisible by n. If `retain` is true,
 then `c1` will have the remainder value after allocation, otherwise the remainder is distributed among the returned currencies.

#### Why does `Allocate(n int, retain bool)` return a slice of currencies?

`Allocate` unlike other operations, cannot be rounded off. If it is rounded, it would result in currency _peddling_.

e.g. ₹1/- (INR 1) is to be divided by 3. There are 2 options of dividing this by 3.

 1. Set 33 paise per split, and retain the remaining 1 paise at source. (`Divide(n, true)`)

 2. Set 1 of the split with an extra value, i.e. 34 + 33 + 33. (`Divide(n, false)`)

### Multiple currency representations

1. `c1.String()`, returns a string representation of the currency value
2. `c1.Float64()`, returns a float64 representation of the currency value

## Benchmarks

How to run?

`$ go test -bench=.`

Results when run on a MacBook Pro (13-inch, M3, 2024), CPU: Apple M3, RAM: 24 GB

```
go version go1.23.1 darwin/arm64
github.com/naughtygopher/currency [allocate]$ go test -bench .
goos: darwin
goarch: arm64
pkg: github.com/naughtygopher/currency/v2
cpu: Apple M3
BenchmarkNew-8 	55541650	 21.68 ns/op
BenchmarkNewFractional-8 	58322852	 21.69 ns/op
BenchmarkParseFloat64-8 	47724391	 25.72 ns/op
BenchmarkParseString-8 	 6650085	 182.2 ns/op
BenchmarkString-8 	20838006	 58.65 ns/op
BenchmarkStringNoPrefix-8 	30418314	 39.87 ns/op
BenchmarkFloat64-8 	1000000000	 0.2722 ns/op
BenchmarkFractionalTotal-8 	1000000000	 0.2697 ns/op
BenchmarkUpdateWithFractional-8 	1000000000	 1.068 ns/op
BenchmarkAdd-8 	190538139	 6.245 ns/op
BenchmarkAddInt-8 	230544486	 5.690 ns/op
BenchmarkSubtract-8 	185860339	 6.537 ns/op
BenchmarkSubtractInt-8 	217542852	 5.571 ns/op
BenchmarkMultiply-8 	282455095	 4.335 ns/op
BenchmarkMultiplyFloat64-8 	84543258	 13.13 ns/op
BenchmarkPercent-8 	52612252	 21.28 ns/op
BenchmarkAllocate-8 	35645416	 34.41 ns/op
PASS
ok 	github.com/naughtygopher/currency/v2	23.125s
```

## References

1. [Ref - Sub unit or fractional unit](<https://en.wikipedia.org/wiki/Denomination_(currency)>)
2. [Ref - Currencies](https://en.wikipedia.org/wiki/Currency) - about currencies
3. [Non-decimal sub unit in currencies are only used by 2 countries today](https://en.wikipedia.org/wiki/Non-decimal_currency). These are getting phased out.

_IMPORTANT! This package does not support sub units which are not a power of 10. Nor does it support currencies with more than 1 sub unit_

## The gopher

The gopher used here was created using [Gopherize.me](https://gopherize.me/). Deal with currency professionally just like this gopher!

# NOWPayments Go Library

[![Go Reference](https://pkg.go.dev/badge/github.com/matm/go-nowpayments.svg)](https://pkg.go.dev/github.com/matm/go-nowpayments)
[![Go Report Card](https://goreportcard.com/badge/github.com/matm/go-nowpayments)](https://goreportcard.com/report/github.com/matm/go-nowpayments)
[![codecov](https://codecov.io/gh/matm/go-nowpayments/branch/main/graph/badge.svg?token=AP16BAZR68)](https://codecov.io/gh/matm/go-nowpayments)

This is an unofficial Go library for the [crypto NOWPayments API](https://documenter.getpostman.com/view/7907941/S1a32n38#84c51632-01ad-49c0-96f8-fb4b5ad2b24a) version 1.

Note that the current implementation mostly focuses on the payments API for now:

Topic|Endpoint|Package.Method|Implemented
---|:---|:---|:---:
[Recurring payments](https://documenter.getpostman.com/view/7907941/S1a32n38#689df54e-9f43-42b3-bfe8-9bcca0444a6a)|||No
[Billing (sub-partner)](https://documenter.getpostman.com/view/7907941/S1a32n38#a523b89b-40b7-4afe-b940-043d434a6c80)|||No
[Payments](https://documenter.getpostman.com/view/7907941/S1a32n38#84c51632-01ad-49c0-96f8-fb4b5ad2b24a)|||Yes
||Get estimated price|[payments.EstimatedPrice(...)](https://pkg.go.dev/github.com/matm/go-nowpayments/pkg/payments#EstimatedPrice)|:heavy_check_mark:
||Get the minimum payment amount|[payments.MinimumAmount(...)](https://pkg.go.dev/github.com/matm/go-nowpayments/pkg/payments#MinimumAmount)|:heavy_check_mark:
||Get payment status|[payments.Status()](https://pkg.go.dev/github.com/matm/go-nowpayments/pkg/payments#Status)|:heavy_check_mark:
||Get list of payments|[payments.List(...)](https://pkg.go.dev/github.com/matm/go-nowpayments/pkg/payments#List)|:heavy_check_mark:
||Get/Update payment estimate|[payments.RefreshEstimatedPrice(...)](https://pkg.go.dev/github.com/matm/go-nowpayments/pkg/payments#RefreshEstimatedPrice)|:heavy_check_mark:
||Create invoice|[payments.NewInvoice(...)](https://pkg.go.dev/github.com/matm/go-nowpayments/pkg/payments#NewInvoice)|:heavy_check_mark:
||Create payment|[payments.New(...)](https://pkg.go.dev/github.com/matm/go-nowpayments/pkg/payments#New)|:heavy_check_mark:
||Create payment from invoice|[payments.NewFromInvoice(...)](https://pkg.go.dev/github.com/matm/go-nowpayments/pkg/payments#NewFromInvoice)|:heavy_check_mark:
[Currencies](https://documenter.getpostman.com/view/7907941/S1a32n38#cb80ccdc-8f7c-426c-89df-1ed2241954a5)|||Yes
||Get available currencies|[currencies.All()](https://pkg.go.dev/github.com/matm/go-nowpayments/pkg/currencies#All)|:heavy_check_mark:
||Get available checked currencies|[currencies.Selected()](https://pkg.go.dev/github.com/matm/go-nowpayments/pkg/currencies#Selected)|:heavy_check_mark:
[Payouts](https://documenter.getpostman.com/view/7907941/S1a32n38#138ee72b-4c4f-40d0-a565-4a1e907f4d94)|||No
[API status](https://documenter.getpostman.com/view/7907941/S1a32n38#9998079f-dcc8-4e07-9ac7-3d52f0fd733a)|||Yes
||Get API status|[core.Status()](https://pkg.go.dev/github.com/matm/go-nowpayments/pkg/core#Status)|:heavy_check_mark:
[Authentication](https://documenter.getpostman.com/view/7907941/S1a32n38#174cd8c5-5973-4be7-9213-05567f8adf27)|||Yes
||Authentication|[core.Authenticate(...)](https://pkg.go.dev/github.com/matm/go-nowpayments/pkg/core#Authenticate)|:heavy_check_mark:

## Installation

```bash
$ go get github.com/matm/go-nowpayments@v1.0.4
```

## Usage

Just load the config with all the credentials from a file or using a `Reader` then display the NOWPayments' API status and the last 2 payments
made with:

```go
package main

import (
	"fmt"
	"log"
	"strings"

	"github.com/matm/go-nowpayments/config"
	"github.com/matm/go-nowpayments/core"
	"github.com/matm/go-nowpayments/payments"
)

func main() {
      // Load sandbox's credentials.
	err := config.Load(strings.NewReader(`
{
      "server": "https://api-sandbox.nowpayments.io/v1",
      "login": "some_email@domain.tld",
      "password": "some_password",
      "apiKey": "some_api_key"
}
`))
	if err != nil {
		log.Fatal(err)
	}

	// Use the server URL defined above.
	core.UseBaseURL(core.BaseURL(config.Server()))
	// Use default HTTP client.
	core.UseClient(core.NewHTTPClient())

	st, err := core.Status()
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("API status:", st)

	const limit = 2
	ps, err := payments.List(&payments.ListOption{
		Limit: limit,
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("Last %d payments: %v\n", limit, ps)
}
```

## CLI Tool

A `np` tool is available to easily play with the payments API from the command line. Please make sure to target the sandbox API server in this case.

Can be installed with:
```bash
$ go install github.com/matm/go-nowpayments/cmd/np@latest
```

The following commands are available:
```
Usage of np:
  -a float
        pay amount for new payment/invoice (default 2)
  -c    show list of selected currencies
  -case string
        payment's case (sandbox only) (default "success")
  -debug
        turn debugging on
  -f string
        JSON config file to use
  -i    new invoice
  -l    list all payments
  -n    new payment
  -p string
        status of payment ID
  -pc string
        crypto currency to pay in (default "xmr")
  -pi string
        new payment from invoice ID
```

In order to work, `np` expects a JSON config file provided as an argument, like
```
$ np -f conf.json -c
```
to list all crypto currencies available for payments.

The JSON config file looks like
```json
{
  "server": "https://api-sandbox.nowpayments.io/v1",
  "login": "your_email_adresse",
  "password": "some_password",
  "apiKey": "the API key to use"
}
```

- `server` is the path to the API server, i.e. one of
  - sandbox: `https://api-sandbox.nowpayments.io/v1`
  - production: `https://api.nowpayments.io/v1`
- `login` and `password` are your NOWPayments credentials
- `apiKey` is one API key generated in your admin account



go-nowpayments

Invoice and billing document framework. JSON Schema based. Automates tax calculations and validation, with tooling to convert into global formats

# GOBL

<img src="https://github.com/invopop/gobl/blob/main/gobl_logo_black_rgb.svg#gh-light-mode-only" width="181" height="219" alt="GOBL Logo">
<img src="https://github.com/invopop/gobl/blob/main/gobl_logo_white_rgb.svg#gh-dark-mode-only" width="181" height="219" alt="GOBL Logo">

Go Business Language. Core library, schemas, and CLI.

Released under the Apache 2.0 [LICENSE](https://github.com/invopop/gobl/blob/main/LICENSE), Copyright 2021-2025 [Invopop S.L.](https://invopop.com).

[![Lint](https://github.com/invopop/gobl/actions/workflows/lint.yaml/badge.svg)](https://github.com/invopop/gobl/actions/workflows/lint.yaml)
[![Test Go](https://github.com/invopop/gobl/actions/workflows/test.yaml/badge.svg)](https://github.com/invopop/gobl/actions/workflows/test.yaml)
[![Go Report Card](https://goreportcard.com/badge/github.com/invopop/gobl)](https://goreportcard.com/report/github.com/invopop/gobl)
[![codecov](https://codecov.io/gh/invopop/gobl/graph/badge.svg?token=490W2CZVIT)](https://codecov.io/gh/invopop/gobl)
[![GoDoc](https://godoc.org/github.com/invopop/gobl?status.svg)](https://godoc.org/github.com/invopop/gobl)
![Latest Tag](https://img.shields.io/github/v/tag/invopop/gobl)
[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/invopop/gobl)
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go)

[Official GOBL documentation site](https://docs.gobl.org).

## Introduction

GOBL, the Go Business Language library and tools, aim to:

- Help developers build electronic business documents, especially invoices, anywhere in the world.
- Define a set of open [JSON Schema](https://json-schema.org/).
- Build a global database of local tax categories and, whenever practical to do so, provide current and historical tax rates in code.
- Validate business documents according to local requirements, including tax ID validation.
- Define the algorithms used to make tax calculations while avoiding rounding errors.
- Provide built-in support for signing documents using [JSON Web Signatures](https://en.wikipedia.org/wiki/JSON_Web_Signature).
- Output simple and easy-to-read JSON documents that emphasize the use of keys instead of abstract codes, like `credit-transfer` instead of `30` (UNTDID4461 code for sender-initiated bank or wire transfer).
- Be flexible enough to support extreme local complexity but produce output that is easily legible in other countries.
- Build a global community of contributors tired of the complexity of current standards based on XML or EDI.

For examples on what GOBL document data looks like, please see the [examples directory](https://github.com/invopop/gobl/tree/main/examples).

## Community

The complexity around invoicing, particularly electronic invoicing, can quickly become overwhelming. Check out the following resources and get in touch:

- [Documentation](https://docs.gobl.org) contains details on how to use GOBL, and the schema.
- [Builder](https://build.gobl.org) helps try out GOBL and quickly figure out what is possible, all from your browser.
- [Issues](https://github.com/invopop/gobl/issues) if you have a specific problem with GOBL related to code or usage.
- [Discussions](https://github.com/invopop/gobl/discussions) for open discussions about the future of GOBL, complications with a specific country, or any open-ended issues.
- [Pull Requests](https://github.com/invopop/gobl/pulls) are very welcome, especially if you'd like to see a new local country or features.
- [Slack](https://join.slack.com/t/goblschema/shared_invite/zt-20qu1s0cm-AUE8oYbGly681EsYdDiqxw) for real-time chat about something specific or urgent. We always encourage you to use one of the other options, which are indexed and searchable, but if you'd like to bring something to attention quickly, this is a great resource.

## Companion Projects

GOBL makes it easy to create business documents, like invoices, but check out some of the companion projects that help create, use, and convert into other formats:

- [Builder](https://github.com/invopop/gobl.builder) - Available to try at [build.gobl.org](https://build.gobl.org), this tool makes it easy to build, test, and discover the features of GOBL using the [wasm](https://webassembly.org/) binary in the browser.
- [Generator](https://github.com/invopop/gobl.generator) - Ruby project to convert GOBL JSON Schema into libraries for other languages or documentation.
- [Docs](https://github.com/invopop/gobl.docs) - Content of the official GOBL Documentation Site [docs.gobl.org](https://docs.gobl.org).
- [GOBL for Ruby](https://github.com/invopop/gobl.ruby) - Easily build or read GOBL documents in Ruby.

Conversion to local and international formats:

- [GOBL to HTML](https://github.com/invopop/gobl.html) - generate printable versions of GOBL documents ready to be converted to PDF.
- [GOBL to FacturaE (Spain)](https://github.com/invopop/gobl.facturae) - convert into the [Spanish FacturaE](https://www.facturae.gob.es/Paginas/Index.aspx) format.
- [GOBL to CFDI (Mexico)](https://github.com/invopop/gobl.cfdi) - convert into the Mexican CFDI format.
- [GOBL to FatturaPA (Italy)](https://github.com/invopop/gobl.fatturapa) - convert into the [Italian FatturaPA](https://www.fatturapa.gov.it/it/index.html) format.
- [GOBL to FA_VAT / KSeF (Poland)](https://github.com/invopop/gobl.ksef) - convert to the Polish FA_VAT format and send to [KSeF](https://www.podatki.gov.pl/ksef/)
- [GOBL to TicketBAI (Spain/Euskadi)](https://github.com/invopop/gobl.ticketbai) - convert into [TicketBAI](https://www.batuz.eus/fitxategiak/batuz/ticketbai/ticketBaiV1-2.xsd) documents, required in the Euskadi (northern region of Spain)
- [GOBL to VERI\*FACTU (Spain)](https://github.com/invopop/gobl.verifactu) - convert and send to the Spanish tax authorities.
- [GOBL UBL](https://github.com/invopop/gobl.ubl) - convert to and from the OASIS Universal Business Language, including support for local and global profiles such as for Peppol and XRechnung (Germany)
- [GOBL CII](https://github.com/invopop/gobl.cii) - convert to and from the Cross Industry Invoice (CII) XML format, including regional variants including Factur-X (France), ZUGFeRD and XRechnung (Germany).
- [GOBL to Stripe](https://github.com/invopop/gobl.stripe) - support for creating GOBL invoices from stripe API data.

## Usage

GOBL is primarily a Go library, so the following instructions assume you'd like to build documents from your own Go applications. See some of the links above if you'd like to develop in another language or use a CLI.

### Installation

Run the following command to install the package:

```
go get github.com/invopop/gobl
```

### Building an Invoice

There are many different ways to get data into GOBL, but for the following example, we're going to try to build an invoice in several steps.

First define a minimal or "partial" GOBL Invoice Document:

```go
inv := &bill.Invoice{
	Series: "F23",
	Code: "00010",
	IssueDate: cal.MakeDate(2023, time.May, 11),
	Supplier: &org.Party{
		TaxID: &tax.Identity{
			Country: l10n.US,
		},
		Name: "Provider One Inc.",
		Alias: "Provider One",
		Emails: []*org.Email{
			{
				Address: "billing@provideone.com",
			},
		},
		Addresses: []*org.Address{
			{
				Number: "16",
				Street: "Jessie Street",
				Locality: "San Francisco",
				Region: "CA",
				Code: "94105",
				Country: l10n.US,
			},
		},
	},
	Customer: &org.Party{
		Name: "Sample Customer",
		Emails: []*org.Email{
			{
				Address: "email@sample.com",
			},
		},
	},
	Lines: []*bill.Line{
		{
			Quantity: num.MakeAmount(20, 0),
			Item: &org.Item{
				Name: "A stylish mug",
				Price: num.MakeAmount(2000, 2),
				Unit: org.UnitHour,
			},
			Taxes: []*tax.Combo{
				{
					Category: common.TaxCategoryST,
					Percent: num.NewPercentage(85, 3),
				},
			},
		},
	},
}
```

Notice that the are no sums or calculations yet. The next step involves "inserting" the invoice document into an "envelope". In GOBL, we use the concept of an envelope to hold data and provide functionality to guarantee that no modifications have been made to the payload.

Insert our previous Invoice into an envelope as follows:

```go
// Prepare an "Envelope"
env := gobl.NewEnvelope()
if err := env.Insert(inv); err != nil {
	panic(err)
}
```

## CLI

This repo contains a `gobl` CLI tool which can be used to manipulate GOBL documents from the command line or shell scripts.

Build with:

```sh
mage -v build
```

Install with:

```sh
mage -v install
```

### Build

Build expects a partial GOBL Envelope or Document, in either YAML or JSON as input. It'll automatically run the Calculate and Validate methods and output JSON data as either an envelope or document, according to the input source.

Example uses:

```sh
# Calculate and validate a YAML invoice
gobl build ./examples/es/invoice-es-es.yaml

# Output using indented formatting
gobl build -i ./examples/es/party.yaml

# Set the supplier from an external file
gobl build -i ./examples/es/invoice-es-es.yaml \
 --set-file customer=./examples/es/party.yaml

# Set arbitrary values from the command line. Inputs are parsed as YAML.
gobl build -i ./examples/es/invoice-es-es.yaml \
 --set meta.bar="a long string" \
 --set series="TESTING"

# Set the top-level object:
gobl build -i ./examples/es/invoice-es-es.yaml \
 --set-file .=./examples/es/invoice-es-es.env.yaml

# Insert a document into an envelope
gobl build -i --envelop ./examples/es/invoice-es-es.yaml
```

### Correct

The GOBL CLI makes it easy to use the library and tax regime specific functionality that create a corrective document that reverts or amends a previous document. This is most useful for invoices and issuing refunds for example.

```sh
# Correct an invoice with a credit note (this will error for ES invoice!)
gobl correct -i ./examples/es/invoice-es-es.yaml --credit

# Specify tax regime specific details
gobl correct -i -d '{"credit":true,"changes":["line"],"method":"complete"}' \
 ./examples/es/invoice-es-es.yaml
```

### Sign

GOBL encourages users to sign data embedded into envelopes using digital signatures. To get started, you'll need to have a JSON Web Key. Use the following commands to generate one:

```sh
# Generate a JSON Web Key and store in ~/.gobl/id_es256.jwk
gobl keygen

# Generate and output a JWK into a new file
gobl keygen ./examples/key.jwk
```

Use the key to sign documents:

```sh
# Add a signature to the envelope using our personal key
gobl sign -i ./examples/es/invoice-es-es.env.yaml

# Add a signature using a specific key
gobl sign -i --key ./examples/key.jwk ./examples/es/invoice-es-es.env.yaml
```

It is only possible to sign non-draft envelopes, so the CLI will automatically remove this flag during the signing process. This implies that the document must be completely valid before signing.

## Development

GOBL uses the `go generate` command to automatically generate JSON schemas, definitions, and some Go code output. After any changes, be sure to run:

```bash
go generate .
```

gobl

Technical analysis library providing financial indicators, strategies, and backtesting framework

[![GoDoc](https://godoc.org/github.com/cinar/indicator/v2?status.svg)](https://godoc.org/github.com/cinar/indicator/v2) [![License](https://img.shields.io/badge/License-AGPLv3-blue.svg)](https://opensource.org/licenses/AGPLv3) [![Go Report Card](https://goreportcard.com/badge/github.com/cinar/indicator/v2)](https://goreportcard.com/report/github.com/cinar/indicator/v2) ![Go CI](https://github.com/cinar/indicator/actions/workflows/ci.yml/badge.svg) [![codecov](https://codecov.io/gh/cinar/indicator/graph/badge.svg?token=MB7L69UAWM)](https://codecov.io/gh/cinar/indicator) [![GHCR Version](https://img.shields.io/github/v/tag/cinar/indicator?label=ghcr&sort=semver&logo=github)](https://github.com/cinar/indicator/pkgs/container/indicator)


 <img src="logo.png" />


Indicator Go
============

Indicator is a Golang module that provides a rich set of technical analysis indicators, strategies, and a framework for backtesting.

### Major improvements in v2:

-	**Enhanced Code Quality:** A complete rewrite was undertaken to achieve and maintain at least 90% code coverage.
-	**Improved Testability:** Each indicator and strategy have dedicated test data in CSV format for easier validation.
-	**Streamlined Data Handling:** The library was rewritten to operate on data streams (Go channels) for both inputs and outputs. If you prefer using slices, helper functions like [helper.SliceToChan](helper/README.md#SliceToChan) and [helper.ChanToSlice](helper/README.md#ChanToSlice) are available. Alternatively, you can still use the [v1 version](https://github.com/cinar/indicator/tree/v1).
-	**Configurable Indicators and Strategies:** All indicators and strategies were designed to be fully configurable with no preset values.
-	**Generics Support:** The library leverages Golang generics to support various numeric data formats.
- **MCP Support:** MCP (Multi-Client Protocol Server) support is integrated into the library, facilitating its use with various AI tools.

I also have a TypeScript version of this module now at [Indicator TS](https://github.com/cinar/indicatorts).

👆 Indicators Provided
----------------------

The following list of indicators are currently supported by this package:

### 📈 Trend Indicators

-	[Absolute Price Oscillator (APO)](trend/README.md#Apo)
- [Alligator Indicator](trend/README.md#Alligator)
-	[Aroon Indicator](trend/README.md#Aroon)
-	[Balance of Power (BoP)](trend/README.md#Bop)
-	[Chande Forecast Oscillator (CFO)](trend/README.md#Cfo)
-	[Commodity Channel Index (CCI)](trend/README.md#Cci)
- [Envelope](trend/README.md#Envelope)
-	[Hull Moving Average (HMA)](trend/README.md#Hma)
- [Detrended Price Oscillator (DPO)](trend/README.md#Dpo)
-	[Double Exponential Moving Average (DEMA)](trend/README.md#Dema)
-	[Exponential Moving Average (EMA)](trend/README.md#Ema)
-	[Kaufman's Adaptive Moving Average (KAMA)](trend/README.md#Kama)
-	[Know Sure Thing (KST)](trend/README.md#Kst)
-	[Mass Index (MI)](trend/README.md#MassIndex)
-	[McGinley Dynamic](trend/README.md#McGinleyDynamic)
-	[Moving Average Convergence Divergence (MACD)](trend/README.md#Macd)
-	[Moving Least Square (MLS)](trend/README.md#Mls)
-	[Moving Linear Regression (MLR)](trend/README.md#Mlr)
-	[Moving Max](trend/README.md#MovingMax)
-	[Moving Min](trend/README.md#MovingMin)
-	[Moving Sum](trend/README.md#MovingSum)
-	[Pivot Point](trend/README.md#PivotPoint)
-	[Random Index (KDJ)](trend/README.md#Kdj)
-	[Stochastic](trend/README.md#Stochastic)
-	[Slow Stochastic](trend/README.md#SlowStochastic)
-	[Schaff Trend Cycle (STC)](trend/README.md#Stc)
-	[Rolling Moving Average (RMA)](trend/README.md#Rma)
-	[Simple Moving Average (SMA)](trend/README.md#Sma)
-	[Since Change](helper/README.md#Since)
- [Smoothed Moving Average (SMMA)](trend/README.md#Smma)
-	[Triple Exponential Moving Average (TEMA)](trend/README.md#Tema)
-	[Triangular Moving Average (TRIMA)](trend/README.md#Trima)
-	[Triple Exponential Average (TRIX)](trend/README.md#Trix)
-	[True Strength Index (TSI)](trend/README.md#Tsi)
-	[Tillson T3](trend/README.md#T3)
-	[Typical Price](trend/README.md#TypicalPrice)
-	[Volume Weighted Moving Average (VWMA)](trend/README.md#Vwma)
- [Weighted Close](trend/README.md#WeightedClose)
-	[Weighted Moving Average (WMA)](trend/README.md#Wma)

### 🚀 Momentum Indicators

-	[Awesome Oscillator](momentum/README.md#AwesomeOscillator)
-	[Chaikin Oscillator](momentum/README.md#ChaikinOscillator)
-	[Connors RSI](momentum/README.md#ConnorsRsi)
-	[Coppock Curve](momentum/README.md#CoppockCurve)
-	[Elder-Ray Index](momentum/README.md#ElderRay)
-	[Fisher Transform](momentum/README.md#Fisher)
-	[Ichimoku Cloud](momentum/README.md#IchimokuCloud)
-	[Percentage Price Oscillator (PPO)](momentum/README.md#Ppo)
-	[Percentage Volume Oscillator (PVO)](momentum/README.md#Pvo)
- [Martin Pring's Special K](momentum/README.md#PringsSpecialK)
-	[Relative Strength Index (RSI)](momentum/README.md#Rsi)
-	[Relative Vigor Index (RVI)](momentum/README.md#Rvi)
-	[Qstick](momentum/README.md#Qstick)
-	[Stochastic Oscillator](momentum/README.md#StochasticOscillator)
-	[Stochastic RSI](momentum/README.md#StochasticRsi)
-	[TD Sequential](momentum/README.md#TdSequential)

### 🎢 Volatility Indicators

- [Percent B](volatility/README.md#PercentB)
-	[Acceleration Bands](volatility/README.md#AccelerationBands)
-	[Average True Range (ATR)](volatility/README.md#Atr)
-	[Bollinger Band Width](volatility/README.md#BollingerBandWidth)
-	[Bollinger Bands](volatility/README.md#BollingerBands)
-	[Chandelier Exit](volatility/README.md#ChandelierExit)
-	[Choppiness Index (CHOP)](volatility/README.md#Chop)
-	[Donchian Channel (DC)](volatility/README.md#DonchianChannel)
-	[Keltner Channel (KC)](volatility/README.md#KeltnerChannel)
-	[Moving Standard Deviation (Std)](volatility/README.md#MovingStd)
-	[Projection Oscillator (PO)](volatility/README.md#Po)
-	[Super Trend](volatility/README.md#SuperTrend)
-	[Ulcer Index (UI)](volatility/README.md#UlcerIndex)

### 📢 Volume Indicators

-	[Accumulation/Distribution (A/D)](volume/README.md#Ad)
-	[Chaikin Money Flow (CMF)](volume/README.md#Cmf)
-	[Ease of Movement (EMV)](volume/README.md#Emv)
-	[Force Index (FI)](volume/README.md#Fi)
-	[Klinger Volume Oscillator (KVO)](volume/README.md#Kvo)
-	[Money Flow Index (MFI)](volume/README.md#Mfi)
-	[Money Flow Multiplier (MFM)](volume/README.md#Mfm)
-	[Money Flow Volume (MFV)](volume/README.md#Mfv)
-	[Negative Volume Index (NVI)](volume/README.md#Nvi)
-	[On-Balance Volume (OBV)](volume/README.md#Obv)
-	[Volume Price Trend (VPT)](volume/README.md#Vpt)
-	[Volume Weighted Average Price (VWAP)](volume/README.md#Vwap)

### 💰 Asset Valuation
- [Future Value (FV)](valuation/README.md#Fv)
- [Net Present Value (NPV)](valuation/README.md#Npv)
- [Present Value (PV)](valuation/README.md#Pv)

🧠 Strategies Provided
----------------------

The following list of strategies are currently supported by this package:

### ⚖ Base Strategies

-	[Buy and Hold Strategy](strategy/README.md#type-buyandholdstrategy)

### 📈 Trend Strategies

- [Alligator Strategy](strategy/trend/README.md#AlligatorStrategy)
-	[Absolute Price Oscillator (APO) Strategy](strategy/trend/README.md#ApoStrategy)
-	[Aroon Strategy](strategy/trend/README.md#AroonStrategy)
-	[Balance of Power (BoP) Strategy](strategy/trend/README.md#BopStrategy)
-	[Chande Forecast Oscillator Strategy](strategy/trend/README.md#CfoStrategy)
-	[Commodity Channel Index (CCI) Strategy](strategy/trend/README.md#CciStrategy)
-	[Double Exponential Moving Average (DEMA) Strategy](strategy/trend/README.md#DemaStrategy)
- [Envelope Strategy](strategy/trend/README.md#EnvelopeStrategy)
-	[Golden Cross Strategy](strategy/trend/README.md#GoldenCrossStrategy)
-	[Kaufman's Adaptive Moving Average (KAMA) Strategy](strategy/trend/README.md#KamaStrategy)
-	[Moving Average Convergence Divergence (MACD) Strategy](strategy/trend/README.md#MacdStrategy)
-	[Qstick Strategy](strategy/trend/README.md#QstickStrategy)
-	[Random Index (KDJ) Strategy](strategy/trend/README.md#KdjStrategy)
- [Smoothed Moving Average (SMMA) Strategy](strategy/trend/README.md#SmmaStrategy)
-	[Triangular Moving Average (TRIMA) Strategy](strategy/trend/README.md#TrimaStrategy)
-	[Triple Exponential Average (TRIX) Strategy](strategy/trend/README.md#TrixStrategy)
-	[Triple Moving Average Crossover Strategy](strategy/trend/README.md#TripleMovingAverageCrossoverStrategy)
-	[True Strength Index (TSI) Strategy](strategy/trend/README.md#TsiStrategy)
-	[Volume Weighted Moving Average (VWMA) Strategy](strategy/trend/README.md#VwmaStrategy)
- [Weighted Close Strategy](strategy/trend/README.md#WeightedCloseStrategy)

### 🚀 Momentum Strategies

-	[Awesome Oscillator Strategy](strategy/momentum/README.md#AwesomeOscillatorStrategy)
-	[Ichimoku Cloud Strategy](strategy/momentum/README.md#IchimokuCloudStrategy)
-	[RSI Strategy](strategy/momentum/README.md#RsiStrategy)
-	[Stochastic RSI Strategy](strategy/momentum/README.md#StochasticRsiStrategy)
-	[Triple RSI Strategy](strategy/momentum/README.md#TripleRsiStrategy)

### 🎢 Volatility Strategies

-	[Bollinger Bands Strategy](strategy/volatility/README.md#BollingerBandsStrategy)
-	[Super Trend Strategy](strategy/volatility/README.md#SuperTrendStrategy)

### 📢 Volume Strategies

-	[Chaikin Money Flow Strategy](strategy/volume/README.md#ChaikinMoneyFlowStrategy)
-	[Ease of Movement Strategy](strategy/volume/README.md#EaseOfMovementStrategy)
-	[Force Index Strategy](strategy/volume/README.md#ForceIndexStrategy)
-	[Money Flow Index Strategy](strategy/volume/README.md#MoneyFlowIndexStrategy)
-	[Negative Volume Index Strategy](strategy/volume/README.md#NegativeVolumeIndexStrategy)
-	[Percent Band and MFI Strategy](strategy/volume/README.md#PercentBandMFIStrategy)
-	[Weighted Average Price Strategy](strategy/volume/README.md#WeightedAveragePriceStrategy)

### 🧪 Compound Strategies

Compound strategies merge multiple strategies to produce integrated recommendations. They combine individual strategies' recommendations using various decision-making logic.

-	[And Strategy](strategy/README.md#AndStrategy)
-	[Majority Strategy](strategy/README.md#MajorityStrategy)
-	[MACD-RSI Strategy](strategy/compound/README.md#MacdRsiStrategy)
-	[Or Strategy](strategy/README.md#OrStrategy)
-	[Split Strategy](strategy/README.md#SplitStrategy)

### 🎁 Decorator Strategies

Decorator strategies offer a way to alter the recommendations of other strategies.

- [Inverse Strategy](strategy/decorator/README.md#InverseStrategy)
- [No Loss Strategy](strategy/decorator/README.md#NoLossStrategy)
- [Stop Loss Strategy](strategy/decorator/README.md#StopLossStrategy)

🗃 Repositories
--------------

Repository serves as a centralized storage and retrieval location for [asset snapshots](asset/README.md#Snapshot).

The following [repository implementations](asset/README.md#Repository) are provided.

-	[File System Repository](asset/README.md#FileSystemRepository)
-	[In Memory Repository](asset/README.md#InMemoryRepository)
-	[Tiingo Repository](asset/README.md#TiingoRepository)
-	[Alpaca Markets Repository](https://github.com/cinar/indicatoralpaca)

The [Sync function](asset/README.md#Sync) facilitates the synchronization of assets between designated source and target repositories by employing multi-worker concurrency for enhanced efficiency. This function serves the purpose of procuring the most recent snapshots from remote repositories and seamlessly transferring them to local repositories, such as file system repositories.

The `indicator-sync` command line tool also offers the capability of synchronizing data between the Tiingo Repository and the File System Repository. To illustrate its usage, consider the following example command:

```bash
$ indicator-sync \
 -source-name tiingo \
 -source-config $TIINGO_KEY \
 -target-name filesystem \
 -target-config /home/user/assets \
 -days 30
```

This command effectively retrieves the most recent snapshots for assets residing within the `/home/user/assets` directory from the Tiingo Repository. In the event that the local asset file is devoid of content, it automatically extends its reach to synchronize 30 days' worth of snapshots, ensuring a comprehensive and up-to-date repository.

⏳ Backtesting
--------------

The [Backtest functionality](backtest/README.md#Backtest), using the [Outcome](strategy/README.md#Outcome), rigorously evaluates the potential performance of the specified strategies applied to a defined set of assets. It generates comprehensive visual representations for each strategy-asset pairing.

```go
report := backtest.NewHTMLReport(outputDir)
bt := backtest.NewBacktest(repository, report)
bt.Names = append(bt.Names, "brk-b")
bt.Strategies = append(bt.Strategies, trend.NewApoStrategy())

err = bt.Run()
if err != nil {
	t.Fatal(err)
}
```

The `indicator-backtest` command line tool empowers users to conduct comprehensive backtesting of assets residing within a specified repository. This capability encompasses the application of all currently recognized strategies, culminating in the generation of detailed reports within a designated output directory.

```bash
$ indicator-backtest \
 -source-name filesystem \
 -source-config /home/user/assets \
 -output /home/user/reports \
 -workers 1
```

☁️ MCP Server
--------------

The [MCP Server](mcp/README.md) (Multi-Client Protocol Server) provides a robust and scalable solution for serving trading strategies to multiple clients. It enables real-time strategy execution and data processing, making it ideal for applications requiring high-throughput and low-latency interactions with trading algorithms.

🐳 Docker
---------

The easiest way to get started is using our Docker image. It handles everything - syncing market data from Tiingo and generating backtest reports - in a single command.

### Quick Start

```bash
# Get your free Tiingo API key at: https://www.tiingo.com/

# Run backtest for specific assets
docker run -it --rm \
 -v $(pwd)/output:/app/output \
 ghcr.io/cinar/indicator:latest \
 --api-key YOUR_TIINGO_API_KEY \
 --days 365 \
 --assets aapl msft googl

# View results (macOS)
open output/index.html

# View results (Linux)
xdg-open output/index.html
```

### Options

| Flag | Description | Default |
|------|-------------|---------|
| `--api-key` | Tiingo API key (required) | - |
| `--days` | Days of historical data to fetch | 365 |
| `--last` | Days to backtest | 365 |
| `--assets` | Space-separated ticker symbols (default: all) | all |
| `--output` | Output directory for reports | /app/output |

### Examples

```bash
# Backtest all available assets for 1 year
docker run -it --rm \
 -v $(pwd)/reports:/app/output \
 ghcr.io/cinar/indicator:latest \
 --api-key YOUR_TIINGO_API_KEY

# Backtest specific stocks for last 6 months, test last 30 days
docker run -it --rm \
 -v $(pwd)/reports:/app/output \
 ghcr.io/cinar/indicator:latest \
 --api-key YOUR_TIINGO_API_KEY \
 --days 180 \
 --last 30 \
 --assets aapl msft googl amzn

# Custom output directory
docker run -it --rm \
 -v /path/to/my/reports:/app/output \
 ghcr.io/cinar/indicator:latest \
 --api-key YOUR_TIINGO_API_KEY \
 --output /app/output
```

### Build Locally

```bash
docker build -t indicator .
docker run -it --rm -v $(pwd)/output:/app/output indicator --api-key YOUR_KEY
```

Usage
-----

Install package.

```bash
go get github.com/cinar/indicator/v2
```

Import indicator.

```Golang
import (
 "github.com/cinar/indicator/v2"
)
```

🌐 Ecosystem
------------

Indicator Go is part of a broader ecosystem of technical analysis tools:

- [Indicator TS](https://github.com/cinar/indicatorts) - TypeScript/JavaScript implementation of the same indicators and strategies
- [Indicator Alpaca](https://github.com/cinar/indicatoralpaca) - Alpaca Markets integration for live trading
- [MCP Server](mcp/README.md) - Model Context Protocol server for AI integration

💖 Our Sponsors
---------------

Indicator is a community-supported project. The following companies, organizations, and individuals help make our work possible. Become [a sponsor](https://github.com/sponsors/cinar) and help us continue to grow!

![Our Sponsors](./sponsors.svg)

Contributing to the Project
---------------------------

Anyone can contribute to Indicator library. Please make sure to read our [Contributor Covenant Code of Conduct](./CODE_OF_CONDUCT.md) guide first. Follow the [How to Contribute to Indicator](./CONTRIBUTING.md) to contribute. Signining a [Contributor Agreement](./CLA.md) is also required to contribute to the project.

Disclaimer
----------

The information provided on this project is strictly for informational purposes and is not to be construed as advice or solicitation to buy or sell any security.

License
-------

The `v2.x.x` and above are dual-licensed under GNU AGPLv3 License and a commercial license. For free use and modifications of the code, you can use the AGPLv3 license. If you require commercial license with different terms, please contact me.

```
Copyright (c) 2021-2026 Onur Cinar. 
The source code is provided under GNU AGPLv3 License.

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published
by the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program. If not, see <https://www.gnu.org/licenses/>.
```

The version `v1.x.x` is provided under MIT License.

```
Copyright (c) 2021-2026 Onur Cinar.
The source code is provided under MIT License.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```

indicator

A programmable financial ledger that provides a foundation for money-moving applications

<img src="https://formance01.b-cdn.net/Github-Attachements/banners/ledger-readme-banner.webp" alt="ledger" width="100%" />


# Formance Ledger

Formance Ledger is a programmable financial core ledger that provides a foundation for all kind of money-moving applications. It provides an atomic multi-postings transactions system, account-based modeling, and is programmable in [numscript](https://docs.formance.com/modules/numscript/introduction), a built-in DSL to model financial transactions.

The ledger can be used either as a standalone micro-service or as part of the [Formance Platform](https://www.formance.com/). It will shine for financial applications requiring a centralized state-keeping of the assets they orchestrate, such as:

* Users balances holding apps, where the ownership of funds held in FBO accounts need to be fine-grained in a ledger
* Digital assets platforms and exchanges, where funds in various denominations are represented
* Payment systems, where funds are cycled through a series of steps from acquiring to payouts
* Loan managment systems, where a sophisticated structure of amounts dues and to be disbursed are orchestrated

Is uses PostgreSQL as its main transactional storage layer and comes with a built-in mechanism to ship ledger logs to replica data stores for OLAP optimized querying.

## Localhost ⚡

To quickly get started using the Formance Ledger on your computer, you can use the local-optimized, all-in-one docker image:

```
docker compose -f examples/standalone/docker-compose.yml up
```

Which will start:
* A Postgres DB
* 1 Gateway Server process (Caddy based reverse proxy)
* 1 Ledger server process
* 1 Ledger worker process
* The Console UI

With the system is up and running, you can now start using the ledger:

```shell
# Create a ledger
http POST :8080/api/ledger/v2/quickstart
# Create a first transaction
http POST :8080/api/ledger/v2/quickstart/transactions postings:='[{"amount":100,"asset":"USD/2","destination":"users:1234","source":"world"}]'
```

And get a visual feedback on the Ledger Console UI started on [http://localhost:3000/formance/localhost?region=localhost](http://localhost:3000/formance/localhost?region=localhost):

![console](https://formance01.b-cdn.net/Github-Attachements/console-screenshot.png)

## Production 🛡️

Production usage of the Formance Ledger is (only) supported through the official k8s [operator](https://github.com/formancehq/operator) deployment mode. Follow the [installation instructions](https://docs.formance.com/build/deployment/operator/installation) to learn more.

## Artifacts 📦

Standalone binary builds can be downloaded from the [releases page](https://github.com/formancehq/ledger/releases).
Container images can be found on the [ghcr registry](https://github.com/formancehq/ledger/pkgs/container/ledger).

## Docs 📚

You can find the exhaustive Formance Platform documentation at [docs.formance.com](https://docs.formance.com).

## Community 💬

If you need help, want to show us what you built or just hang out and chat about ledgers you are more than welcome in our [GitHub Discussions](https://github.com/orgs/formancehq/discussions) - looking forward to see you there!

## Contributing 🛠️

See [CONTRIBUTING.md](./CONTRIBUTING.md)

ledger

Immutable monetary amounts and exchange rates with panic-free arithmetic

# money

[![githubb]][github]
[![codecovb]][codecov]
[![goreportb]][goreport]
[![godocb]][godoc]
[![licenseb]][license]
[![versionb]][version]
[![awesomeb]][awesome]

Package money implements immutable monetary amounts and exchange rates for Go.

## Key Features

- **Immutability** - Once set, an amount or exchange rate remains constant,
  ensuring safe concurrent access across goroutines.
- **Banker's Rounding** - Uses half-to-even rounding, also known as "banker's rounding",
  to minimize cumulative rounding errors commonly seen in financial calculations.
- **No Panics** - All methods are panic-free, returning errors instead of crashing
  your application in cases such as overflow, division by zero, or currency mismatch.
- **Zero Heap Allocation** - Optimized to avoid heap allocations,
  reducing garbage collector impact during arithmetic operations.
- **High Precision** - Supports up to 19 digits of precision, representing amounts
  from -99,999,999,999,999,999.99 to 99,999,999,999,999,999.99 inclusive.
- **Correctness** - Arithmetic operations are cross-validated against the
  [cockroachdb/apd] and [shopspring/decimal] packages through extensive [fuzz testing].

## Getting Started

### Installation

To add the money package to your Go workspace:

```bash
go get github.com/govalues/money
```

### Basic Usage

Create an amount using one of the constructors.
After creating an amount, you can perform various operations as shown below:

```go
package main

import (
    "fmt"
    "github.com/govalues/decimal"
    "github.com/govalues/money"
)

func main() {
    // Constructors
    a, _ := money.NewAmount("USD", 8, 0)               // a = $8.00
    b, _ := money.ParseAmount("USD", "12.5")           // b = $12.50
    c, _ := money.NewAmountFromFloat64("USD", 2.567)   // c = $2.567
    d, _ := money.NewAmountFromInt64("USD", 7, 896, 3) // d = $7.896
    r, _ := money.NewExchRate("USD", "EUR", 9, 1)      // r = $/€ 0.9
    x, _ := decimal.New(2, 0)                          // x = 2

    // Operations
    fmt.Println(a.Add(b))          // $8.00 + $12.50
    fmt.Println(a.Sub(b))          // $8.00 - $12.50
    fmt.Println(a.SubAbs(b))       // abs($8.00 - $12.50)

    fmt.Println(a.Mul(x))          // $8.00 * 2
    fmt.Println(a.AddMul(b, x))    // $8.00 + $12.50 * 2
    fmt.Println(a.SubMul(b, x))    // $8.00 - $12.50 * 2
    fmt.Println(r.Conv(a))         // $8.00 * $/€ 0.9

    fmt.Println(a.Quo(x))          // $8.00 / 2
    fmt.Println(a.AddQuo(b, x))    // $8.00 + $12.50 / 2
    fmt.Println(a.SubQuo(b, x))    // $8.00 - $12.50 / 2
    fmt.Println(a.QuoRem(x))       // $8.00 div 2, $8.00 mod 2
    fmt.Println(a.Rat(b))          // $8.00 / $12.50
    fmt.Println(a.Split(3))        // $8.00 into 3 parts

    // Rounding to 2 decimal places
    fmt.Println(c.RoundToCurr())   // 2.57
    fmt.Println(c.CeilToCurr())    // 2.57
    fmt.Println(c.FloorToCurr())   // 2.56
    fmt.Println(c.TruncToCurr())   // 2.56

    // Conversions
    fmt.Println(d.Int64(9))        // 7 896000000
    fmt.Println(d.Float64())       // 7.896
    fmt.Println(d.String())        // USD 7.896

    // Formatting
    fmt.Printf("%v", d)            // USD 7.896
    fmt.Printf("%[1]f %[1]c", d)   // 7.896 USD
    fmt.Printf("%f", d)            // 7.896
    fmt.Printf("%c", d)            // USD
    fmt.Printf("%d", d)            // 790
}
```

## Documentation

For detailed documentation and additional examples, visit the package
[documentation](https://pkg.go.dev/github.com/govalues/money#section-documentation).

## Comparison

Comparison with other popular packages:

| Feature                         | govalues       | [rhymond] v1.0.10 | [bojanz] v1.2.1 |
| ------------------------------- | -------------- | ----------------- | --------------- |
| Speed                           | High           | Medium            | Medium          |
| Numeric Representation          | Floating Point | Fixed Point       | Floating Point  |
| Precision                       | 19 digits      | 18 digits         | 39 digits       |
| Default Rounding                | Half to even   | Not supported     | Half up         |
| Overflow Control                | Yes            | No[^wrap]         | Yes             |
| Support for Division            | Yes            | No                | Yes             |
| Support for Currency Conversion | Yes            | No                | Yes             |

[^wrap]: [rhymond] does not detect overflow and returns an invalid result.
For example, 92,233,720,368,547,758.07 + 0.01 results in -92,233,720,368,547,758.08.

### Benchmarks

```text
goos: linux
goarch: amd64
pkg: github.com/govalues/money-tests
cpu: AMD Ryzen 7 3700C  with Radeon Vega Mobile Gfx 
```

| Test Case     | Expression            | govalues | [rhymond] v1.0.10 | [bojanz] v1.2.1 | govalues vs rhymond | govalues vs bojanz |
| ------------- | --------------------- | -------: | ----------------: | --------------: | ------------------: | -----------------: |
| Add           | $2.00 + $3.00         |   22.95n |           218.30n |         144.10n |            +851.41% |           +528.02% |
| Mul           | $2.00 * 3             |   21.80n |           133.40n |         239.60n |            +511.79% |           +998.83% |
| Quo (exact)   | $2.00 / 4             |   80.12n |               n/a |         468.05n |                 n/a |           +484.19% |
| Quo (inexact) | $2.00 / 3             |   602.1n |               n/a |          512.4n |                 n/a |            -14.91% |
| Split         | $2.00 into 10 parts   |   374.9n |            897.0n |             n/a |            +139.28% |                n/a |
| Conv          | $2.00 to €            |   30.88n |               n/a |         348.50n |                 n/a |          +1028.38% |
| Parse         | $1                    |   44.99n |           139.50n |          99.09n |            +210.07% |           +120.26% |
| Parse         | $123.456              |   61.45n |           148.60n |         240.90n |            +141.82% |           +292.03% |
| Parse         | $123456789.1234567890 |   131.2n |            204.4n |          253.0n |             +55.85% |            +92.87% |
| String        | $1                    |   38.48n |           200.70n |          89.92n |            +421.50% |           +133.65% |
| String        | $123.456              |   56.34n |           229.90n |         127.05n |            +308.02% |           +125.49% |
| String        | $123456789.1234567890 |   84.73n |           383.30n |         277.55n |            +352.38% |           +227.57% |
| Telco         | see [specification]   |   224.2n |               n/a |         1944.0n |                 n/a |           +766.89% |

The benchmark results shown in the table are provided for informational purposes
only and may vary depending on your specific use case.

[codecov]: https://codecov.io/gh/govalues/money
[codecovb]: https://img.shields.io/codecov/c/github/govalues/money/main?color=brightcolor
[goreport]: https://goreportcard.com/report/github.com/govalues/money
[goreportb]: https://goreportcard.com/badge/github.com/govalues/money
[github]: https://github.com/govalues/money/actions/workflows/go.yml
[githubb]: https://img.shields.io/github/actions/workflow/status/govalues/money/go.yml
[godoc]: https://pkg.go.dev/github.com/govalues/money#section-documentation
[godocb]: https://img.shields.io/badge/go.dev-reference-blue
[version]: https://go.dev/dl
[versionb]: https://img.shields.io/github/go-mod/go-version/govalues/money?label=go
[license]: https://en.wikipedia.org/wiki/MIT_License
[licenseb]: https://img.shields.io/github/license/govalues/money?color=blue
[awesome]: https://github.com/avelino/awesome-go#financial
[awesomeb]: https://awesome.re/mentioned-badge.svg
[rhymond]: https://pkg.go.dev/github.com/Rhymond/go-money
[bojanz]: https://pkg.go.dev/github.com/bojanz/currency
[cockroachdb/apd]: https://pkg.go.dev/github.com/cockroachdb/apd
[shopspring/decimal]: https://pkg.go.dev/github.com/shopspring/decimal
[specification]: https://speleotrove.com/decimal/telcoSpec.html
[fuzz testing]: https://github.com/govalues/decimal-tests


money

Query OFX servers and/or parse the responses (with example command-line client)

# OFXGo

[![Go Report Card](https://goreportcard.com/badge/github.com/aclindsa/ofxgo)](https://goreportcard.com/report/github.com/aclindsa/ofxgo)
[![Build Status](https://github.com/aclindsa/ofxgo/workflows/ofxgo%20CI%20Test/badge.svg?branch=master)](https://github.com/aclindsa/ofxgo/actions?query=workflow%3A%22ofxgo+CI+Test%22+branch%3Amaster)
[![Coverage Status](https://coveralls.io/repos/github/aclindsa/ofxgo/badge.svg?branch=master)](https://coveralls.io/github/aclindsa/ofxgo?branch=master)
[![PkgGoDev](https://pkg.go.dev/badge/github.com/aclindsa?ofxgo)](https://pkg.go.dev/github.com/aclindsa/ofxgo)

**OFXGo** is a library for querying OFX servers and/or parsing the responses. It
also provides an example command-line client to demonstrate the use of the
library.

## Goals

The main purpose of this project is to provide a library to make it easier to
query financial information with OFX from the comfort of Golang, without having
to marshal/unmarshal to SGML or XML. The library does _not_ intend to abstract
away all of the details of the OFX specification, which would be difficult to do
well. Instead, it exposes the OFX SGML/XML hierarchy as structs which mostly
resemble it. Its primary goal is to enable the creation of other personal
finance software in Go (as it was created to allow me to fetch OFX transactions
for my own project, [MoneyGo](https://github.com/aclindsa/moneygo)).

Because the OFX specification is rather... 'comprehensive,' it can be difficult
for those unfamiliar with it to figure out where to start. To that end, I have
created a sample command-line client which uses the library to do simple tasks
(currently it does little more than list accounts and query for balances and
transactions). My hope is that by studying its code, new users will be able to
figure out how to use the library much faster than staring at the OFX
specification (or this library's [API
documentation](https://pkg.go.dev/github.com/aclindsa/ofxgo)). The command-line client
also serves as an easy way for me to test/debug the library with actual
financial institutions, which frequently have 'quirks' in their implementations.
The command-line client can be found in the [cmd/ofx
directory](https://github.com/aclindsa/ofxgo/tree/master/cmd/ofx) of this
repository.

## Library documentation

Documentation can be found with the `go doc` tool, or at
https://pkg.go.dev/github.com/aclindsa/ofxgo

## Example Usage

The following code snippet demonstrates how to use OFXGo to query and parse
OFX code from a checking account, printing the balance and returned transactions:

```go
client := ofxgo.BasicClient{} // Accept the default Client settings

// These values are specific to your bank
var query ofxgo.Request
query.URL = "https://secu.example.com/ofx"
query.Signon.Org = ofxgo.String("SECU")
query.Signon.Fid = ofxgo.String("1234")

// Set your username/password
query.Signon.UserID = ofxgo.String("username")
query.Signon.UserPass = ofxgo.String("hunter2")

uid, _ := ofxgo.RandomUID() // Handle error in real code
query.Bank = append(query.Bank, &ofxgo.StatementRequest{
	TrnUID: *uid,
	BankAcctFrom: ofxgo.BankAcct{
		BankID: ofxgo.String("123456789"), // Possibly your routing number
		AcctID: ofxgo.String("00011122233"), // Possibly your account number
		AcctType: ofxgo.AcctTypeChecking,
	},
	Include: true, // Include transactions (instead of only balance information)
})

response, _ := client.Request(&query) // Handle error in real code

// Was there an OFX error while processing our request?
if response.Signon.Status.Code != 0 {
	meaning, _ := response.Signon.Status.CodeMeaning()
	fmt.Printf("Nonzero signon status (%d: %s) with message: %s\n", response.Signon.Status.Code, meaning, response.Signon.Status.Message)
	os.Exit(1)
}

if len(response.Bank) < 1 {
	fmt.Println("No banking messages received")
	os.Exit(1)
}

if stmt, ok := response.Bank[0].(*ofxgo.StatementResponse); ok {
	fmt.Printf("Balance: %s %s (as of %s)\n", stmt.BalAmt, stmt.CurDef, stmt.DtAsOf)
	fmt.Println("Transactions:")
	for _, tran := range stmt.BankTranList.Transactions {
		currency := stmt.CurDef
		if ok, _ := tran.Currency.Valid(); ok {
			currency = tran.Currency.CurSym
		}
		fmt.Printf("%s %-15s %-11s %s%s%s\n", tran.DtPosted, tran.TrnAmt.String()+" "+currency.String(), tran.TrnType, tran.Name, tran.Payee.Name, tran.Memo)
	}
}
```

Similarly, if you have an OFX file available locally, you can parse it directly:

```go
func main() {
	f, err := os.Open("./transactions.qfx")
	if err != nil {
		fmt.Printf("can't open file: %v\n", err)
		return
	}
	defer f.Close()

	resp, err := ofxgo.ParseResponse(f)
	if err != nil {
		fmt.Printf("can't parse response: %v\n", err)
		return
	}

	// do something with resp (*ofxgo.Response)
}
```

## Requirements

OFXGo requires go >= 1.12

## Using the command-line client

To install the command-line client and test it out, you may do the following:

$ go get -v github.com/aclindsa/ofxgo/cmd/ofx && go install -v github.com/aclindsa/ofxgo/cmd/ofx

Once installed (at ~/go/bin/ofx by default, if you haven't set $GOPATH), the
command's usage should help you to use it (`./ofx --help` for a listing of the
available subcommands and their purposes, `./ofx subcommand --help` for
individual subcommand usage).

ofxgo

High performance, high precision, zero allocation fixed-point decimal library for financial applications

# udecimal

[![build](https://github.com/quagmt/udecimal/actions/workflows/test.yaml/badge.svg)](https://github.com/quagmt/udecimal/actions/workflows/test.yaml)
[![Go Report Card](https://goreportcard.com/badge/github.com/quagmt/udecimal)](https://goreportcard.com/report/github.com/quagmt/udecimal)
[![codecov](https://codecov.io/gh/quagmt/udecimal/graph/badge.svg?token=662ET843EZ)](https://codecov.io/gh/quagmt/udecimal)
[![GoDoc](https://pkg.go.dev/badge/github.com/quagmt/udecimal)](https://pkg.go.dev/github.com/quagmt/udecimal)
[![Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go#financial)

High performance, high precision, zero allocation fixed-point decimal number for financial applications.

## Installation

Supported version: Go >= 1.23

```sh
go get github.com/quagmt/udecimal
```

## Features

- **High Precision**: Supports up to 19 decimal places with no precision loss during arithmetic operations.
- **Zero Memory Allocation**: Designed for almost 99% zero memory allocation (see [How it works](#how-it-works)).
- **Optimized for Speed**: 5x~20x faster than [shopspring/decimal](https://github.com/shopspring/decimal) and [ericlagergren/decimal](https://github.com/ericlagergren/decimal) (see [Benchmark](benchmarks/README.md)).
- **Panic-Free**: All errors are returned as values, ensuring no unexpected panics.
- **Concurrent-Safe**: All arithmetic operations return a new `Decimal` value while keeping the original value unchanged, making it safe to be shared across goroutines.
- **Correctness**: All arithmetic operations are fuzz tested and cross-checked with `shopspring/decimal` library to ensure correctness.
- **Versatile Rounding Methods**: Includes HALF AWAY FROM ZERO, HALF TOWARD ZERO, AWAY FROM ZERO, and Banker's rounding.
 

**NOTE**: This library does not perform implicit rounding. If the result of an operation exceeds the maximum precision, extra digits are truncated. All rounding methods must be explicitly invoked. (see [Rounding Methods](#rounding-methods) for more details)

## Documentation

- Checkout [documentation](https://pkg.go.dev/github.com/quagmt/udecimal) for more information.

## Usage

```go
package main

import (
	"fmt"

	"github.com/quagmt/udecimal"
)

func main() {
	// Create a new decimal number
	a, _ := udecimal.NewFromInt64(123456, 3) // a = 123.456
	b, _ := udecimal.NewFromInt64(-123456, 4) // b = -12.3456
	c, _ := udecimal.NewFromFloat64(1.2345) // c = 1.2345
	d, _ := udecimal.Parse("4123547.1234567890123456789") // d = 4123547.1234567890123456789

	// Basic arithmetic operations
	fmt.Println(a.Add(b)) // 123.456 - 12.3456 = 111.1104
	fmt.Println(a.Sub(b)) // 123.456 + 12.3456 = 135.8016
	fmt.Println(a.Mul(b)) // 123.456 * -12.3456 = -1524.1383936
	fmt.Println(a.Div(b)) // 123.456 / -12.3456 = -10
	fmt.Println(a.Div(d)) // 123.456 / 4123547.1234567890123456789 = 0.0000299392722585176

	// Rounding
	fmt.Println(c.RoundBank(3)) // banker's rounding: 1.2345 -> 1.234
	fmt.Println(c.RoundAwayFromZero(2)) // round away from zero: 1.2345 -> 1.24
	fmt.Println(c.RoundHAZ(3)) // half away from zero: 1.2345 -> 1.235
	fmt.Println(c.RoundHTZ(3)) // half towards zero: 1.2345 -> 1.234
	fmt.Println(c.Trunc(2)) // truncate: 1.2345 -> 1.23
	fmt.Println(c.Floor()) // floor: 1.2345 -> 1
	fmt.Println(c.Ceil()) // ceil: 1.2345 -> 2

	// Display
	fmt.Println(a.String()) // 123.456
	fmt.Println(a.StringFixed(10)) // 123.4560000000
	fmt.Println(a.InexactFloat64()) // 123.456
}
```

## Why another decimal library?

There are already a couple of decimal libraries available in Go, such as [shopspring/decimal](https://github.com/shopspring/decimal), [cockroachdb/apd](https://github.com/cockroachdb/apd), [govalues/decimal](https://github.com/govalues/decimal), etc. However, each of these libraries has its own limitations, for example:

- [shopspring/decimal](https://github.com/shopspring/decimal) is great for general-purpose decimal arithmetic because of arbitrary precision. However, it's slow and requires memory allocation for every arithmetic operation. Also in financial applications, arbitrary precision is not always necessary.
- [cockroachdb/apd](https://github.com/cockroachdb/apd) is faster but still requires memory allocation. Also the API is not very intuitive.
- [govalues/decimal](https://github.com/govalues/decimal) is fast, no memory allocation, easy to use but the data range is only limited to 19 digits (include both the integer and fractional parts). Some operations (especially Quo/QuoRem) usually overflow and fallback to use big.Int API, which hurts the performance. Another limitation is that it starts losing precision when the total number of digits exceeds 19.

This library is designed to address these limitations, providing both high performance and zero allocation while maintaining an acceptable range of precision, which is suitable for most financial applications.

## Rounding Methods

Rounding numbers can often be challenging and confusing due to the [variety of methods](https://www.mathsisfun.com/numbers/rounding-methods.html) available. Each method serves specific purposes, and it's common for developers to make mistakes or incorrect assumptions about how rounding should be performed. For example, the result of `round(1.45)` could be either 1.4 or 1.5, depending on the rounding method used.

This issue is particularly critical in financial applications, where even minor rounding errors can accumulate and lead to significant financial losses. To mitigate such errors, this library intentionally avoids implicit rounding. If the result of an operation exceeds the maximum precision specified by developers beforehand, **extra digits are truncated**. Developers need to explicitly choose the rounding method they want to use. The supported rounding methods are:

- [Banker's rounding](https://en.wikipedia.org/wiki/Rounding#Rounding_half_to_even) or round half to even
- [Round away from zero](https://en.wikipedia.org/wiki/Rounding#Rounding_away_from_zero)
- [Half away from zero](https://en.wikipedia.org/wiki/Rounding#Rounding_half_away_from_zero) (HAZ)
- [Half toward zero](https://en.wikipedia.org/wiki/Rounding#Rounding_half_toward_zero) (HTZ)

### Examples:

```go
package main

import (
	"fmt"

	"github.com/quagmt/udecimal"
)

func main() {
	// Create a new decimal number
	a, _ := udecimal.NewFromFloat64(1.345) // a = 1.345

	// Rounding
	fmt.Println(a.RoundBank(2)) // banker's rounding: 1.345 -> 1.34
	fmt.Println(a.RoundAwayFromZero(2)) // round away from zero: 1.345 -> 1.35
	fmt.Println(a.RoundHAZ(2)) // half away from zero: 1.345 -> 1.35
	fmt.Println(a.RoundHTZ(2)) // half towards zero: 1.345 -> 1.34
}
```

## How it works

As mentioned above, this library is not always memory allocation free. However, those cases where we need to allocate memory are incredibly rare. To understand why, let's take a look at how the `Decimal` type is implemented.

The `Decimal` type represents a fixed-point decimal number. It consists of three components: sign, coefficient, and prec. The number is represented as:

```go
// decimal value = (neg == true ? -1 : 1) * coef * 10^(-prec)
type Decimal struct {
	coef bint
	neg bool
	prec uint8 // 0 <= prec <= 19
}

// Example:
// 123.456 = 123456 * 10^-3
// -> neg = false, coef = 123456, prec = 3

// -123.456 = -123456 / 10^-3
// -> neg = true, coef = 123456, prec = 3
```

You can notice that `coef` data type is `bint`, which is a custom data type:

```go
type bint struct {
	// For coefficients exceeding u128
	bigInt *big.Int

	// For coefficients less than 2^128
	u128 u128
}
```

The `bint` type can store coefficients up to `2^128 - 1` using `u128`. Arithmetic operations with `u128` are fast and require no memory allocation. If result of an arithmetic operation exceeds u128 capacity, the whole operation will be performed using `big.Int` API. Such operations are slower and do involve memory allocation. However, those cases are rare in financial applications due to the extensive range provided by a 128-bit unsigned integer, for example:

- If precision is 0, the decimal range it can store is:
 `[-340282366920938463463374607431768211455, 340282366920938463463374607431768211455]`(approximately -340 to 340 undecillion)

- If precision is 19, the decimal range becomes:
 `[-34028236692093846346.3374607431768211455, 34028236692093846346.3374607431768211455]` (approximately -34 to 34 quintillion)

Therefore, in most cases you can expect high performance and no memory allocation when using this library.

## Credits

This library is inspired by these repositories:

- [govalues/decimal](https://github.com/govalues/decimal)
- [lukechampine/uint128](https://github.com/lukechampine/uint128)
- [ridiculousfish/libdivide](https://github.com/ridiculousfish/libdivide)

The Best Go Libraries For Financial (29)

currency

decimal

currency

decimal

fpdecimal

fpmoney

accounting

ach

bbgo

go-money

go-finnhub

orderbook

payme

ticker

sleet

transaction

go-finance

go-finance

techan

vat

dec128

currency

go-nowpayments

gobl

indicator

ledger

money

ofxgo

udecimal