orderbook

package
v0.0.0-...-ca62b0a Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Dec 9, 2024 License: MIT Imports: 15 Imported by: 182

README

GoCryptoTrader package Orderbook

Build Status Software License GoDoc Coverage Status Go Report Card

This orderbook package is part of the GoCryptoTrader codebase.

This is still in active development

You can track ideas, planned features and what's in progress on our GoCryptoTrader Kanban board.

Join our slack to discuss all things related to GoCryptoTrader! GoCryptoTrader Slack

Current Features for orderbook

  • This package facilitates orderbook generation.

  • Attaches methods to an orderbook

    • To Return total Bids
    • To Return total Asks
    • Update orderbooks
  • Gets a loaded orderbook by exchange, asset type and currency pair.

  • This package is primarily used in conjunction with but not limited to the exchange interface system set by exchange wrapper orderbook functions in "exchange"_wrapper.go.

Examples below:

ob, err := yobitExchange.FetchOrderbook()
if err != nil {
	// Handle error
}

// Find total asks which also returns total orderbook value
totalAsks, totalOrderbookVal := ob.CalculateTotalAsks()
  • or if you have a routine setting an exchange orderbook you can access it via the package itself.
ob, err := orderbook.Get(...)
if err != nil {
	// Handle error
}
Please click GoDocs chevron above to view current GoDoc information for this package

Contribution

Please feel free to submit any pull requests or suggest any desired features to be added.

When submitting a PR, please abide by our coding guidelines:

  • Code must adhere to the official Go formatting guidelines (i.e. uses gofmt).
  • Code must be documented adhering to the official Go commentary guidelines.
  • Code must adhere to our coding style.
  • Pull requests need to be based on and opened against the master branch.

Donations

If this framework helped you in any way, or you would like to support the developers working on it, please donate Bitcoin to:

bc1qk0jareu4jytc0cfrhr5wgshsq8282awpavfahc

Documentation

Index

Constants

View Source
const FullLiquidityExhaustedPercentage = -100

FullLiquidityExhaustedPercentage defines when a book has been completely wiped out of potential liquidity.

Variables

View Source
var (
	// ErrOrderbookInvalid defines an error for when the orderbook is invalid and
	// should not be trusted
	ErrOrderbookInvalid = errors.New("orderbook data integrity compromised")
	// ErrInvalidAction defines and error when an action is invalid
	ErrInvalidAction = errors.New("invalid action")
)

Functions

func SubscribeToExchangeOrderbooks

func SubscribeToExchangeOrderbooks(exchange string) (dispatch.Pipe, error)

SubscribeToExchangeOrderbooks returns a pipe to an exchange feed

Types

type Action

type Action uint8

Action defines a set of differing states required to implement an incoming orderbook update used in conjunction with UpdateEntriesByID

const (
	// Amend applies amount adjustment by ID
	Amend Action = iota + 1
	// Delete removes price level from book by ID
	Delete
	// Insert adds price level to book
	Insert
	// UpdateInsert on conflict applies amount adjustment or appends new amount
	// to book
	UpdateInsert
)

type Base

type Base struct {
	Bids Tranches
	Asks Tranches

	Exchange string
	Pair     currency.Pair
	Asset    asset.Item

	// LastUpdated is the time when a change occurred on the exchange books.
	// Note: This does not necessarily indicate the change is out of sync with
	// the exchange. It represents the last known update time from the exchange,
	// which could be stale if there have been no recent changes.
	LastUpdated time.Time

	// UpdatePushedAt is the time the exchange pushed this update. This helps
	// determine factors like distance from exchange (latency) and routing
	// time, which can affect the time it takes for an update to reach the user
	// from the exchange.
	UpdatePushedAt time.Time

	// InsertedAt is the time the update was inserted into the orderbook
	// management system. This field is used to calculate round-trip times and
	// processing delays, e.g., InsertedAt.Sub(UpdatePushedAt) represents the
	// total processing time including network latency.
	InsertedAt time.Time

	LastUpdateID int64
	// PriceDuplication defines whether an orderbook can contain duplicate
	// prices in a payload
	PriceDuplication bool
	IsFundingRate    bool
	// VerifyOrderbook allows for a toggle between orderbook verification set by
	// user configuration, this allows for a potential processing boost but
	// a potential for orderbook integrity being deminished.
	VerifyOrderbook bool
	// RestSnapshot defines if the depth was applied via the REST protocol thus
	// an update cannot be applied via websocket mechanics and a resubscription
	// would need to take place to maintain book integrity
	RestSnapshot bool
	// Checks if the orderbook needs ID alignment as well as price alignment
	IDAlignment bool
	// Determines if there is a max depth of orderbooks and after an append we
	// should remove any items that are outside of this scope. Kraken utilises
	// this field.
	MaxDepth int
	// ChecksumStringRequired defines if the checksum is built from the raw
	// string representations of the price and amount. This helps alleviate any
	// potential rounding issues.
	ChecksumStringRequired bool
}

Base holds the fields for the orderbook base

func Get

func Get(exchange string, p currency.Pair, a asset.Item) (*Base, error)

Get checks and returns the orderbook given an exchange name and currency pair

func (*Base) GetAveragePrice

func (b *Base) GetAveragePrice(buy bool, amount float64) (float64, error)

GetAveragePrice finds the average buy or sell price of a specified amount. It finds the nominal amount spent on the total purchase or sell and uses it to find the average price for an individual unit bought or sold

func (*Base) GetDepth

func (b *Base) GetDepth() (*Depth, error)

GetDepth returns the concrete book allowing the caller to stream orderbook changes

func (*Base) Process

func (b *Base) Process() error

Process processes incoming orderbooks, creating or updating the orderbook list

func (*Base) SimulateOrder

func (b *Base) SimulateOrder(amount float64, buy bool) (*WhaleBombResult, error)

SimulateOrder simulates an order

func (*Base) TotalAsksAmount

func (b *Base) TotalAsksAmount() (amountCollated, total float64)

TotalAsksAmount returns the total amount of asks and the total orderbook asks value

func (*Base) TotalBidsAmount

func (b *Base) TotalBidsAmount() (amountCollated, total float64)

TotalBidsAmount returns the total amount of bids and the total orderbook bids value

func (*Base) Verify

func (b *Base) Verify() error

Verify ensures that the orderbook items are correctly sorted prior to being set and will reject any book with incorrect values. Bids should always go from a high price to a low price and Asks should always go from a low price to a higher price

func (*Base) WhaleBomb

func (b *Base) WhaleBomb(priceTarget float64, buy bool) (*WhaleBombResult, error)

WhaleBomb finds the amount required to target a price

type DeploymentAction

type DeploymentAction struct {
	ReferencePrice       float64
	TranchePositionPrice float64
	BaseAmount           float64
	QuoteAmount          float64
	Tranches             Tranches
	FullLiquidityUsed    bool
}

DeploymentAction defines deployment information on a liquidity side.

type Depth

type Depth struct {
	alert.Notice
	// contains filtered or unexported fields
}

Depth defines a store of orderbook tranches

func DeployDepth

func DeployDepth(exchange string, p currency.Pair, a asset.Item) (*Depth, error)

DeployDepth sets a depth struct and returns a depth pointer. This allows for the loading of a new orderbook snapshot and incremental updates via the streaming package.

func GetDepth

func GetDepth(exchange string, p currency.Pair, a asset.Item) (*Depth, error)

GetDepth returns a Depth pointer allowing the caller to stream orderbook changes

func NewDepth

func NewDepth(id uuid.UUID) *Depth

NewDepth returns a new orderbook depth

func (*Depth) AssignOptions

func (d *Depth) AssignOptions(b *Base)

AssignOptions assigns the initial options for the depth instance

func (*Depth) DeleteBidAskByID

func (d *Depth) DeleteBidAskByID(update *Update, bypassErr bool) error

DeleteBidAskByID deletes a price level by ID

func (*Depth) GetAskLength

func (d *Depth) GetAskLength() (int, error)

GetAskLength returns length of asks

func (*Depth) GetBestAsk

func (d *Depth) GetBestAsk() (float64, error)

GetBestAsk returns the best ask price

func (*Depth) GetBestBid

func (d *Depth) GetBestBid() (float64, error)

GetBestBid returns the best bid price

func (*Depth) GetBidLength

func (d *Depth) GetBidLength() (int, error)

GetBidLength returns length of bids

func (*Depth) GetImbalance

func (d *Depth) GetImbalance() (float64, error)

GetImbalance returns top orderbook imbalance

func (*Depth) GetMidPrice

func (d *Depth) GetMidPrice() (float64, error)

GetMidPrice returns the mid price between the ask and bid spread

func (*Depth) GetName

func (d *Depth) GetName() string

GetName returns name of exchange

func (*Depth) GetPair

func (d *Depth) GetPair() (currency.Pair, error)

GetPair returns the pair associated with the depth

func (*Depth) GetSpreadAmount

func (d *Depth) GetSpreadAmount() (float64, error)

GetSpreadAmount returns the spread as a quotation amount

func (*Depth) GetSpreadPercentage

func (d *Depth) GetSpreadPercentage() (float64, error)

GetSpreadPercentage returns the spread as a percentage

func (*Depth) GetTranches

func (d *Depth) GetTranches(count int) (ask, bid []Tranche, err error)

GetTranches returns the desired tranche for the required depth count. If count is 0, it will return the entire orderbook. Count == 1 will retrieve the best bid and ask. If the required count exceeds the orderbook depth, it will return the entire orderbook.

func (*Depth) HitTheBids

func (d *Depth) HitTheBids(amount, refPrice float64, purchase bool) (*Movement, error)

HitTheBids derives full orderbook slippage information from reference price using an amount. Purchase refers to how much quote currency is desired else the amount would refer to base currency deployed to orderbook bid side.

func (*Depth) HitTheBidsByImpactSlippage

func (d *Depth) HitTheBidsByImpactSlippage(maxSlippage, refPrice float64) (*Movement, error)

HitTheBidsByImpactSlippage hits the bids by the required impact slippage percentage, calculated from the reference price and returns orderbook movement details for the bid side.

func (*Depth) HitTheBidsByImpactSlippageFromBest

func (d *Depth) HitTheBidsByImpactSlippageFromBest(maxSlippage float64) (*Movement, error)

HitTheBidsByImpactSlippageFromBest hits the bids by the required impact slippage percentage, calculated from the best bid price and returns orderbook movement details for the bid side.

func (*Depth) HitTheBidsByImpactSlippageFromMid

func (d *Depth) HitTheBidsByImpactSlippageFromMid(maxSlippage float64) (*Movement, error)

HitTheBidsByImpactSlippageFromMid hits the bids by the required impact slippage percentage, calculated from the mid price and returns orderbook movement details for the bid side.

func (*Depth) HitTheBidsByNominalSlippage

func (d *Depth) HitTheBidsByNominalSlippage(maxSlippage, refPrice float64) (*Movement, error)

HitTheBidsByNominalSlippage hits the bids by the required nominal slippage percentage, calculated from the reference price and returns orderbook movement details for the bid side.

func (*Depth) HitTheBidsByNominalSlippageFromBest

func (d *Depth) HitTheBidsByNominalSlippageFromBest(maxSlippage float64) (*Movement, error)

HitTheBidsByNominalSlippageFromBest hits the bids by the required nominal slippage percentage, calculated from the best bid price and returns orderbook movement details for the bid side.

func (*Depth) HitTheBidsByNominalSlippageFromMid

func (d *Depth) HitTheBidsByNominalSlippageFromMid(maxSlippage float64) (*Movement, error)

HitTheBidsByNominalSlippageFromMid hits the bids by the required nominal slippage percentage, calculated from the mid price and returns orderbook movement details for the bid side.

func (*Depth) HitTheBidsFromBest

func (d *Depth) HitTheBidsFromBest(amount float64, purchase bool) (*Movement, error)

HitTheBidsFromBest derives full orderbook slippage information from best bid price using an amount. Purchase refers to how much quote currency is desired else the amount would refer to base currency deployed to orderbook bid side.

func (*Depth) HitTheBidsFromMid

func (d *Depth) HitTheBidsFromMid(amount float64, purchase bool) (*Movement, error)

HitTheBidsFromMid derives full orderbook slippage information from mid price using an amount. Purchase refers to how much quote currency is desired else the amount would refer to base currency deployed to orderbook bid side.

func (*Depth) InsertBidAskByID

func (d *Depth) InsertBidAskByID(update *Update) error

InsertBidAskByID inserts new updates

func (*Depth) Invalidate

func (d *Depth) Invalidate(withReason error) error

Invalidate flushes all values back to zero so as to not allow strategy traversal on compromised data.

func (*Depth) IsFundingRate

func (d *Depth) IsFundingRate() bool

IsFundingRate returns if the depth is a funding rate

func (*Depth) IsRESTSnapshot

func (d *Depth) IsRESTSnapshot() (bool, error)

IsRESTSnapshot returns if the depth was updated via REST

func (*Depth) IsValid

func (d *Depth) IsValid() bool

IsValid returns if the underlying book is valid.

func (*Depth) LastUpdateID

func (d *Depth) LastUpdateID() (int64, error)

LastUpdateID returns the last Update ID

func (*Depth) LiftTheAsks

func (d *Depth) LiftTheAsks(amount, refPrice float64, purchase bool) (*Movement, error)

LiftTheAsks derives full orderbook slippage information from reference price using an amount. Purchase refers to how much base currency is desired else the amount would refer to quote currency deployed to orderbook ask side.

func (*Depth) LiftTheAsksByImpactSlippage

func (d *Depth) LiftTheAsksByImpactSlippage(maxSlippage, refPrice float64) (*Movement, error)

LiftTheAsksByImpactSlippage lifts the asks by the required impact slippage percentage, calculated from the reference price and returns orderbook movement details for the ask side.

func (*Depth) LiftTheAsksByImpactSlippageFromBest

func (d *Depth) LiftTheAsksByImpactSlippageFromBest(maxSlippage float64) (*Movement, error)

LiftTheAsksByImpactSlippageFromBest lifts the asks by the required impact slippage percentage, calculated from the best ask price and returns orderbook movement details for the ask side.

func (*Depth) LiftTheAsksByImpactSlippageFromMid

func (d *Depth) LiftTheAsksByImpactSlippageFromMid(maxSlippage float64) (*Movement, error)

LiftTheAsksByImpactSlippageFromMid lifts the asks by the required impact slippage percentage, calculated from the mid price and returns orderbook movement details for the ask side.

func (*Depth) LiftTheAsksByNominalSlippage

func (d *Depth) LiftTheAsksByNominalSlippage(maxSlippage, refPrice float64) (*Movement, error)

LiftTheAsksByNominalSlippage lifts the asks by the required nominal slippage percentage, calculated from the reference price and returns orderbook movement details for the ask side.

func (*Depth) LiftTheAsksByNominalSlippageFromBest

func (d *Depth) LiftTheAsksByNominalSlippageFromBest(maxSlippage float64) (*Movement, error)

LiftTheAsksByNominalSlippageFromBest lifts the asks by the required nominal slippage percentage, calculated from the best ask price and returns orderbook movement details for the ask side.

func (*Depth) LiftTheAsksByNominalSlippageFromMid

func (d *Depth) LiftTheAsksByNominalSlippageFromMid(maxSlippage float64) (*Movement, error)

LiftTheAsksByNominalSlippageFromMid lifts the asks by the required nominal slippage percentage, calculated from the mid price and returns orderbook movement details for the ask side.

func (*Depth) LiftTheAsksFromBest

func (d *Depth) LiftTheAsksFromBest(amount float64, purchase bool) (*Movement, error)

LiftTheAsksFromBest derives full orderbook slippage information from best ask price using an amount. Purchase refers to how much base currency is desired else the amount would refer to quote currency deployed to orderbook ask side.

func (*Depth) LiftTheAsksFromMid

func (d *Depth) LiftTheAsksFromMid(amount float64, purchase bool) (*Movement, error)

LiftTheAsksFromMid derives full orderbook slippage information from mid price using an amount. Purchase refers to how much base currency is desired else the amount would refer to quote currency deployed to orderbook ask side.

func (*Depth) LoadSnapshot

func (d *Depth) LoadSnapshot(bids, asks []Tranche, lastUpdateID int64, lastUpdated, updatePushedAt time.Time, updateByREST bool) error

LoadSnapshot flushes the bids and asks with a snapshot

func (*Depth) Publish

func (d *Depth) Publish()

Publish alerts any subscribed routines using a dispatch mux

func (*Depth) Retrieve

func (d *Depth) Retrieve() (*Base, error)

Retrieve returns the orderbook base a copy of the underlying linked list spread

func (*Depth) TotalAskAmounts

func (d *Depth) TotalAskAmounts() (liquidity, value float64, err error)

TotalAskAmounts returns the total amount of asks and the total orderbook asks value

func (*Depth) TotalBidAmounts

func (d *Depth) TotalBidAmounts() (liquidity, value float64, err error)

TotalBidAmounts returns the total amount of bids and the total orderbook bids value

func (*Depth) UpdateBidAskByID

func (d *Depth) UpdateBidAskByID(update *Update) error

UpdateBidAskByID amends details by ID

func (*Depth) UpdateBidAskByPrice

func (d *Depth) UpdateBidAskByPrice(update *Update) error

UpdateBidAskByPrice updates the bid and ask spread by supplied updates, this will trim total length of depth level to a specified supplied number

func (*Depth) UpdateInsertByID

func (d *Depth) UpdateInsertByID(update *Update) error

UpdateInsertByID updates or inserts by ID at current price level.

func (*Depth) VerifyOrderbook

func (d *Depth) VerifyOrderbook() bool

VerifyOrderbook returns if the verify orderbook option is set

type Exchange

type Exchange struct {
	ID uuid.UUID
	// contains filtered or unexported fields
}

Exchange defines a holder for the exchange specific depth items with a specific ID associated with that exchange

type Movement

type Movement struct {
	// NominalPercentage (real-world) defines how far in percentage terms is
	// your average order price away from the reference price.
	NominalPercentage float64
	// ImpactPercentage defines how far the price has moved on the order book
	// from the reference price.
	ImpactPercentage float64
	// SlippageCost is the cost of the slippage. This is priced in quotation.
	SlippageCost float64
	// StartPrice defines the reference price or the head of the orderbook side.
	StartPrice float64
	// EndPrice defines where the price has ended on the orderbook side.
	EndPrice float64
	// Sold defines the amount of currency sold.
	Sold float64
	// Purchases defines the amount of currency purchased.
	Purchased float64
	// AverageOrderCost defines the average order cost of position as it slips
	// through the orderbook tranches.
	AverageOrderCost float64
	// FullBookSideConsumed defines if the orderbook liquidty has been consumed
	// by the requested amount. This might not represent the actual book on the
	// exchange as they might restrict the amount of information being passed
	// back from either a REST request or websocket stream.
	FullBookSideConsumed bool
}

Movement defines orderbook traversal details from either hitting the bids or lifting the asks.

type Outbound

type Outbound interface {
	Retrieve() (*Base, error)
}

Outbound restricts outbound usage of depth. NOTE: Type assert to *orderbook.Depth.

type Service

type Service struct {
	*dispatch.Mux
	// contains filtered or unexported fields
}

Service provides a store for difference exchange orderbooks

func (*Service) DeployDepth

func (s *Service) DeployDepth(exchange string, p currency.Pair, a asset.Item) (*Depth, error)

DeployDepth used for subsystem deployment creates a depth item in the struct then returns a ptr to that Depth item

func (*Service) GetDepth

func (s *Service) GetDepth(exchange string, p currency.Pair, a asset.Item) (*Depth, error)

GetDepth returns the actual depth struct for potential subsystems and strategies to interact with

func (*Service) Retrieve

func (s *Service) Retrieve(exchange string, p currency.Pair, a asset.Item) (*Base, error)

Retrieve gets orderbook depth data from the stored tranches and returns the base equivalent copy

func (*Service) Update

func (s *Service) Update(b *Base) error

Update stores orderbook data

type SideAmounts

type SideAmounts struct {
	Tranches   int64
	QuoteValue float64
	BaseAmount float64
}

SideAmounts define the amounts total for the tranches, total value in quotation and the cumulative base amounts.

type Tranche

type Tranche struct {
	Amount float64
	// StrAmount is a string representation of the amount. e.g. 0.00000100 this
	// parsed as a float will constrict comparison to 1e-6 not 1e-8 or
	// potentially will round value which is not ideal.
	StrAmount string
	Price     float64
	// StrPrice is a string representation of the price. e.g. 0.00000100 this
	// parsed as a float will constrict comparison to 1e-6 not 1e-8 or
	// potentially will round value which is not ideal.
	StrPrice string
	ID       int64

	// Funding rate field
	Period int64

	// Contract variables
	LiquidationOrders int64
	OrderCount        int64
}

Tranche defines a segmented portions of an order or options book

type Tranches

type Tranches []Tranche

Tranches defines a slice of orderbook Tranche

func (Tranches) FindNominalAmount

func (ts Tranches) FindNominalAmount(amount float64) (aggNominalAmount, remainingAmount float64)

FindNominalAmount finds the nominal amount spent in terms of the quote If the orderbook doesn't have enough liquidity it returns a non zero remaining amount value

func (*Tranches) Reverse

func (ts *Tranches) Reverse()

Reverse reverses the order of orderbook items; some bid/asks are returned in either ascending or descending order. One bid or ask slice depending on what's received can be reversed. This is usually faster than using a sort algorithm as the algorithm could be impeded by a worst case time complexity when elements are shifted as opposed to just swapping element values.

func (Tranches) SortAsks

func (ts Tranches) SortAsks()

SortAsks sorts ask items to the correct ascending order if pricing values are scattered. If order from exchange is descending consider using the Reverse function.

func (Tranches) SortBids

func (ts Tranches) SortBids()

SortBids sorts bid items to the correct descending order if pricing values are scattered. If order from exchange is ascending consider using the Reverse function.

type Update

type Update struct {
	UpdateID       int64 // Used when no time is provided
	UpdateTime     time.Time
	UpdatePushedAt time.Time
	Asset          asset.Item
	Action
	Bids []Tranche
	Asks []Tranche
	Pair currency.Pair
	// Checksum defines the expected value when the books have been verified
	Checksum uint32
}

Update and things and stuff

type WhaleBombResult

type WhaleBombResult struct {
	Amount               float64
	MinimumPrice         float64
	MaximumPrice         float64
	PercentageGainOrLoss float64
	Orders               Tranches
	Status               string
}

WhaleBombResult returns the whale bomb result

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL