Documentation
¶
Overview ¶
Package ledger implements the paper-trading simulated book: an in-memory cash balance, position map, fill journal with client_order_id idempotency, and exact fixed-point fee accounting.
Invariants:
- all money/quantity math uses big.Int scaled decimals, never float64;
- a repeated client_order_id returns the original result unchanged;
- fills are all-or-nothing against displayed top-of-book size;
- nothing here ever touches the network or credentials.
Index ¶
Constants ¶
const ( FeeRateNumerator = 7 FeeRateDenominator = 100 )
FeeRateNumerator / FeeRateDenominator encode Kalshi's published trading fee formula: fee = 0.07 * P * (1-P) per contract.
const JournalCap = 10000
JournalCap bounds memory growth.
Variables ¶
var ( ErrInsufficientBook = errors.New("displayed book size does not cover the requested count") ErrDuplicateOrder = errors.New("client_order_id already filled") ErrNoRestingOrder = errors.New("no resting order to cancel") ErrJournalFull = errors.New("fill journal reached its configured cap") ErrInsufficientCash = errors.New("paper balance insufficient") ErrInvalidInput = errors.New("invalid price or count") )
Typed errors surfaced through mcptools.Error codes.
Functions ¶
Types ¶
type Fill ¶
type Fill struct {
ClientOrderID string `json:"client_order_id"`
Ticker string `json:"ticker"`
Side Side `json:"side"`
PriceDollars string `json:"price_dollars"`
CountFP string `json:"count_fp"`
FeeDollars string `json:"fee_dollars"`
BookHash string `json:"orderbook_hash"`
Simulated bool `json:"simulated"`
At time.Time `json:"at"`
}
Fill records one completed simulation.
type FillRequest ¶
type FillRequest struct {
ClientOrderID string
Ticker string
Side Side
PriceDollars string // limit/fill price quoted by caller (must equal book touch)
CountFP string
BookPrice string // top-of-book dollars from the fetched snapshot
BookSizeFP string // displayed size at that touch
BookHash string // hash of the snapshot used
}
FillRequest describes one simulated order.
type FillResult ¶
type FillResult struct {
Fill *Fill `json:"fill,omitempty"`
Replayed bool `json:"replayed,omitempty"`
CashAfter string `json:"cash_after"`
}
FillResult reports what happened, including idempotent replays.
type Ledger ¶
type Ledger struct {
// contains filtered or unexported fields
}
Ledger is the concurrency-safe paper book.
func (*Ledger) Execute ¶
func (l *Ledger) Execute(req FillRequest) (*FillResult, error)
Execute simulates an immediate all-or-nothing fill.
Pricing rule: a bid (buy YES) pays the ask; an ask (sell YES) hits the bid. The caller passes BookPrice as the touch it wants to cross; we verify the requested PriceDollars equals it to prevent accidental mispricing, then charge fees per the published formula.
type Money ¶
Money is a fixed-point dollar amount as [value, scale]: value * 10^-scale. Prices use scale 4 ("0.5400"); counts use scale 2 ("10.00"). All arithmetic keeps full precision; only final rendering rounds (half-up) to the target scale.
Source Files