marketdata

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Sep 5, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package marketdata provides access to Webull's Market Data API over HTTP: snapshots, quotes, ticks, bars and reference data.

Obtain a Client from the root package: 

client, err := webull.NewClient(webull.Config{...})
snaps, err := client.MarketData.Snapshots(ctx, marketdata.SnapshotsRequest{Symbols: []string{"AAPL"}})

All methods take a context.Context and are safe for concurrent use.

Asset classes

Stocks are the primary surface. Options (OptionSnapshots, with greeks), futures (FuturesSnapshots and friends), crypto (CryptoSnapshots) and event contracts (EventSnapshots, with a book per outcome) have their own methods, since their fields differ. Bars share one type across all of them.

The sandbox serves futures data for a single symbol, "MESmain"; the display-solution event endpoints (per-market snapshots, live data, game stats) do not exist in the sandbox at all and are not implemented.

Fundamentals

Company reference data covers profiles, analyst consensus, financial statements (BalanceSheets, IncomeStatements, CashFlows), indicators, earnings and dividend calendars, capital flow, regulatory filings, EPS forecasts and industry comparison. The sandbox answers the financial-statement and industry-comparison endpoints with empty results for every symbol; the rest serve real data.

Fund data (FundBrief, FundHoldings and friends) uses the same request shape with a fund's symbol. Screeners rank stocks by change, activity, yield, 52-week extremes and sector. Watchlists are the one mutable market-data surface: create, rename, fill, reorder and delete.

News is not implemented: the one documented endpoint is a Server-Sent Events stream that does not exist in the sandbox.

Entitlements

Market data is sold by product. A request for data the key is not subscribed to fails with ErrNotSubscribed, wrapping a *webull.APIError whose message names the product needed, such as "please subscribe to FOOTPRINT". Depth of book is limited to the levels the key is entitled to; asking for more is rejected as an invalid parameter. Futures depth and all footprint data need their own subscriptions.

Hosts

Webull's SDKs route market data to a data-api host. That host does not answer HTTP requests - it is the MQTT streaming broker - and HTTP market data is served by the same host as trading. This package uses the latter.

Time

The API transmits time in three forms: epoch milliseconds as a JSON number, epoch milliseconds as a string, and ISO 8601 with a "+0000" offset that the standard RFC 3339 layout does not accept. Millis and Time decode each of them into a time.Time.

Numbers

Prices, sizes and ratios are decimal strings and are decoded as the SDK's Decimal type, or NullDecimal where the field may be absent - most snapshot fields are, outside a trading session. Both embed shopspring's decimal types. No field is a float.

Index

Examples

Constants

This section is empty.

Variables

View Source 
var ErrNotSubscribed = errors.New("marketdata: not subscribed to this data")

ErrNotSubscribed is returned when the key is not entitled to the data requested. The wrapped *webull.APIError's Message names the product. Because the response is an HTTP 403, the same error also matches webull.ErrPermission.

View Source 
var ErrWatchlistFailed = errors.New("marketdata: webull reported the watchlist operation unsuccessful")

ErrWatchlistFailed is returned when Webull answers a watchlist mutation with HTTP 200 but reports it unsuccessful.

Functions

This section is empty.

Types

type ActivityMetric 

type ActivityMetric string

ActivityMetric is the measure the top-active screener ranks by. 

const (
	ByVolume         ActivityMetric = "VOLUME"
	ByRelativeVolume ActivityMetric = "RELATIVE_VOLUME_10D"
	ByTurnover       ActivityMetric = "TURNOVER"
	ByTurnoverRate   ActivityMetric = "TURNOVER_RATE"
	ByAmplitude      ActivityMetric = "AMPLITUDE"
)

Activity metrics.

type AnalystRating 

type AnalystRating struct {
	Symbol        string   `json:"symbol"`
	Category      Category `json:"category"`
	Analysts      Decimal  `json:"number"`
	StrongBuy     Decimal  `json:"strong_buy"`
	Buy           Decimal  `json:"buy"`
	Hold          Decimal  `json:"hold"`
	UnderPerform  Decimal  `json:"under_perform"`
	Sell          Decimal  `json:"sell"`
	EffectiveFrom Time     `json:"effective_start_date"`
}

AnalystRating is the consensus of analyst recommendations.

type AssetBarsRequest 

type AssetBarsRequest struct {
	// Symbols holds up to 20 symbols.
	Symbols  []string
	Timespan Timespan
	// Count is at most 1200; zero lets Webull apply its default of 200.
	Count int
	// Completed omits the bar still forming.
	//
	// How this reaches the wire depends on the asset class. Crypto and event
	// contracts require the real_time_required parameter and receive it
	// either way; options accept it and receive it only when Completed is
	// set; futures do not document it and never receive it.
	Completed bool
}

AssetBarsRequest selects candles for option, futures, crypto or event contract symbols.

type AssetTicks 

type AssetTicks struct {
	Symbol string `json:"symbol"`
	// InstrumentID is camel-cased on the wire for the option and futures tick
	// endpoints, unlike every other endpoint in the API.
	InstrumentID string `json:"instrumentId"`
	Ticks        []Tick `json:"result"`
}

AssetTicks is an option or futures contract's recent trades, newest first. Option ticks carry an undocumented "NS" Side alongside the documented letters, and no Session.

type BalanceSheet 

type BalanceSheet struct {
	ReportPeriod

	TotalAssets                 NullDecimal `json:"total_assets"`
	TotalCurrentAssets          NullDecimal `json:"total_cur_assets"`
	CashAndShortTermInvest      NullDecimal `json:"cash_st_invest"`
	Cash                        NullDecimal `json:"cash"`
	CashEquivalents             NullDecimal `json:"cash_equiv"`
	ShortTermInvestments        NullDecimal `json:"st_invest"`
	TotalReceivablesNet         NullDecimal `json:"total_recv_net"`
	TradeReceivablesNet         NullDecimal `json:"ar_trade_net"`
	TotalInventory              NullDecimal `json:"total_inv"`
	PrepaidExpenses             NullDecimal `json:"prepaid_expenses"`
	OtherCurrentAssets          NullDecimal `json:"other_cur_assets"`
	TotalNonCurrentAssets       NullDecimal `json:"total_non_cur_assets"`
	PPENet                      NullDecimal `json:"ppe_net"`
	PPEGross                    NullDecimal `json:"ppe_gross"`
	AccumulatedDepreciation     NullDecimal `json:"acc_depre"`
	GoodwillNet                 NullDecimal `json:"goodwill_net"`
	IntangiblesNet              NullDecimal `json:"intangibles_net"`
	LongTermInvestments         NullDecimal `json:"lt_invest"`
	LongTermNotesReceivable     NullDecimal `json:"note_rece_long_term"`
	OtherLongTermAssets         NullDecimal `json:"other_lt_assets"`
	TotalLiabilities            NullDecimal `json:"total_liab"`
	TotalCurrentLiabilities     NullDecimal `json:"total_cur_liab"`
	AccountsPayable             NullDecimal `json:"ap"`
	AccruedExpenses             NullDecimal `json:"accrued_expenses"`
	ShortTermDebt               NullDecimal `json:"notes_st_debt"`
	CurrentLongTermDebt         NullDecimal `json:"cur_lt_debt_lease"`
	OtherCurrentLiabilities     NullDecimal `json:"other_cur_liab"`
	TotalNonCurrentLiabilities  NullDecimal `json:"total_non_cur_liab"`
	TotalLongTermDebt           NullDecimal `json:"total_lt_debt"`
	LongTermDebt                NullDecimal `json:"lt_debt"`
	CapitalLeaseObligations     NullDecimal `json:"capital_lease_obligations"`
	TotalDebt                   NullDecimal `json:"total_debt"`
	OtherLiabilities            NullDecimal `json:"other_liab"`
	MinorityInterest            NullDecimal `json:"minority_interest"`
	TotalEquity                 NullDecimal `json:"total_equity"`
	TotalShareholdersEquity     NullDecimal `json:"total_sh_equity"`
	NonRedeemablePreferredStock NullDecimal `json:"non_redeemable_preferred_stock"`
	CommonStock                 NullDecimal `json:"common_stock"`
	AdditionalPaidInCapital     NullDecimal `json:"apic"`
	RetainedEarnings            NullDecimal `json:"retained_earnings"`
	OtherEquity                 NullDecimal `json:"other_equity"`
	TotalLiabilitiesAndEquity   NullDecimal `json:"total_liab_sh_equity"`
	CommonSharesOutstanding     NullDecimal `json:"common_shares_out"`
}

BalanceSheet is one reporting period's balance sheet. Line items a company does not report are null.

type Bar 

type Bar struct {
	Time    Time           `json:"time"`
	Open    Decimal        `json:"open"`
	High    Decimal        `json:"high"`
	Low     Decimal        `json:"low"`
	Close   Decimal        `json:"close"`
	Volume  Decimal        `json:"volume"`
	Session TradingSession `json:"trading_session"`
}

Bar is one OHLCV candle.

type Bars 

type Bars struct {
	Symbol       string `json:"symbol"`
	InstrumentID string `json:"instrument_id"`
	Bars         []Bar  `json:"result"`
}

Bars is one stock's candles.

type BarsRequest 

type BarsRequest struct {
	// Symbols holds up to 100 symbols.
	Symbols  []string
	Category Category
	Timespan Timespan
	// Count is at most 1200 (1650 for Minute); zero lets Webull apply its
	// default of 200.
	Count int
	// Completed omits the bar still forming.
	Completed bool
	Sessions  []TradingSession
	// Start and End bound the range; zero values are omitted.
	Start time.Time
	End   time.Time
}

BarsRequest selects candles for one or more stocks.

type CapitalFlow 

type CapitalFlow struct {
	Date      Time    `json:"date"`
	LargeIn   Decimal `json:"large_in"`
	LargeOut  Decimal `json:"large_out"`
	MediumIn  Decimal `json:"medium_in"`
	MediumOut Decimal `json:"medium_out"`
	SmallIn   Decimal `json:"small_in"`
	SmallOut  Decimal `json:"small_out"`
}

CapitalFlow is one trading day's traded value broken down by order size, in the market's base currency.

type CashFlow 

type CashFlow struct {
	ReportPeriod

	OperatingCashFlow        NullDecimal `json:"cfo"`
	NetIncome                NullDecimal `json:"net_income"`
	DepreciationAmortization NullDecimal `json:"dna"`
	DeferredTaxes            NullDecimal `json:"deferred_tax"`
	NonCashItems             NullDecimal `json:"non_cash_items"`
	WorkingCapitalChange     NullDecimal `json:"wc_change"`
	InvestingCashFlow        NullDecimal `json:"cfi"`
	CapitalExpenditures      NullDecimal `json:"capex"`
	OtherInvestingItems      NullDecimal `json:"other_cfi_items"`
	FinancingCashFlow        NullDecimal `json:"cff"`
	FinancingItems           NullDecimal `json:"cff_items"`
	NetStockIssuance         NullDecimal `json:"net_stock_iss_ret"`
	NetDebtIssuance          NullDecimal `json:"net_debt_iss_ret"`
	FXEffects                NullDecimal `json:"fx_effects"`
	NetChangeInCash          NullDecimal `json:"net_change_cash"`
	InterestPaid             NullDecimal `json:"interest_paid"`
	TaxesPaid                NullDecimal `json:"taxes_paid"`
}

CashFlow is one reporting period's cash flow statement. Line items a company does not report are null.

type Category 

type Category = wire.Category

Category identifies an asset class in market-data requests. It is an alias of the shared wire type also used by the streaming package. 

const (
	USStock   Category = "US_STOCK"
	USETF     Category = "US_ETF"
	USOption  Category = "US_OPTION"
	USFutures Category = "US_FUTURES"
	USCrypto  Category = "US_CRYPTO"
	USEvent   Category = "US_EVENT"
)

Categories. USStock and USETF are accepted by the stock endpoints; the rest each have their own.

type Client 

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

Client calls the Market Data API. It is safe for concurrent use.

func New 

func New(doer *transport.Doer, host string) *Client

New returns a Client that sends requests through doer to host.

It exists so the root webull package can compose a Client; callers of the SDK should use webull.NewClient.

func (*Client) AddWatchlistInstruments 

func (c *Client) AddWatchlistInstruments(ctx context.Context, id string, entries []WatchlistEntry) error

AddWatchlistInstruments adds instruments to a watchlist.

func (*Client) AnalystRating 

func (c *Client) AnalystRating(ctx context.Context, symbol string, cat Category) (*AnalystRating, error)

AnalystRating returns the consensus analyst rating for a stock.

func (*Client) BalanceSheets 

func (c *Client) BalanceSheets(ctx context.Context, req FinancialsRequest) ([]BalanceSheet, error)

BalanceSheets returns a company's balance sheets, most recent first.

func (*Client) Bars 

func (c *Client) Bars(ctx context.Context, req BarsRequest) ([]Bars, error)

Bars returns candles for each requested stock.

Example

ExampleClient_Bars fetches daily candles. Data the key is not subscribed to fails with ErrNotSubscribed, wrapping an *APIError that names the product. 

package main

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

	"github.com/sfreiberg/webull"
	"github.com/sfreiberg/webull/marketdata"
)

func exampleClient() *webull.Client {
	client, err := webull.NewClient(webull.Config{
		AppKey:      os.Getenv("WEBULL_APP_KEY"),
		AppSecret:   os.Getenv("WEBULL_APP_SECRET"),
		Environment: webull.Sandbox,
	})
	if err != nil {
		log.Fatal(err)
	}
	return client
}

func main() {
	client := exampleClient()

	bars, err := client.MarketData.Bars(context.Background(), marketdata.BarsRequest{
		Symbols:  []string{"AAPL"},
		Timespan: marketdata.Daily,
		Count:    30,
	})
	if errors.Is(err, marketdata.ErrNotSubscribed) {
		log.Fatal("this key is not entitled to the requested data")
	}
	if err != nil {
		log.Fatal(err)
	}
	for _, b := range bars[0].Bars {
		fmt.Println(b.Time, b.Open, b.High, b.Low, b.Close, b.Volume)
	}
}

func (*Client) CapitalFlows 

func (c *Client) CapitalFlows(ctx context.Context, symbol string, cat Category, count int) ([]CapitalFlow, error)

CapitalFlows returns the most recent trading days' capital flow, oldest first. Count is between 1 and 5; zero lets Webull apply its default of 5.

func (*Client) CashFlows 

func (c *Client) CashFlows(ctx context.Context, req FinancialsRequest) ([]CashFlow, error)

CashFlows returns a company's cash flow statements, most recent first.

func (*Client) CompanyProfile 

func (c *Client) CompanyProfile(ctx context.Context, symbol string, cat Category) (*CompanyProfile, error)

CompanyProfile returns the profile of a listed company.

func (*Client) CreateWatchlist 

func (c *Client) CreateWatchlist(ctx context.Context, name string, sort int) (string, error)

CreateWatchlist creates a watchlist and returns its ID. Sort orders it for display; zero lets Webull assign one.

func (*Client) CryptoBars 

func (c *Client) CryptoBars(ctx context.Context, req AssetBarsRequest) ([]Bars, error)

CryptoBars returns candles for crypto pairs. Crypto bars carry no volume; Bar.Volume is zero.

func (*Client) CryptoSnapshots 

func (c *Client) CryptoSnapshots(ctx context.Context, symbols []string) ([]CryptoSnapshot, error)

CryptoSnapshots returns the current state of crypto pairs such as "BTCUSD".

func (*Client) DeleteWatchlist 

func (c *Client) DeleteWatchlist(ctx context.Context, id string) error

DeleteWatchlist deletes a watchlist.

func (*Client) Depth 

func (c *Client) Depth(ctx context.Context, req DepthRequest) (*Depth, error)

Depth returns a stock's order book.

func (*Client) DividendCalendar 

func (c *Client) DividendCalendar(ctx context.Context, symbol string, cat Category) ([]Dividend, error)

DividendCalendar returns a stock's declared dividends.

func (*Client) EarningsCalendar 

func (c *Client) EarningsCalendar(ctx context.Context, symbol string, cat Category) ([]Earnings, error)

EarningsCalendar returns a stock's quarterly earnings dates and estimates.

func (*Client) EventBars 

func (c *Client) EventBars(ctx context.Context, req AssetBarsRequest) ([]Bars, error)

EventBars returns candles for event contract markets.

func (*Client) EventDepth 

func (c *Client) EventDepth(ctx context.Context, symbol string, levels int) (*EventDepth, error)

EventDepth returns an event contract market's order book. levels is per side; zero lets Webull apply its default of ten.

func (*Client) EventSnapshots 

func (c *Client) EventSnapshots(ctx context.Context, symbols []string) ([]EventSnapshot, error)

EventSnapshots returns the current state of event contract markets.

func (*Client) EventTicks 

func (c *Client) EventTicks(ctx context.Context, symbol string, count int) (*EventTicks, error)

EventTicks returns an event contract market's most recent trades. count is at most 1200; zero lets Webull apply its default of 30.

func (*Client) Filings 

func (c *Client) Filings(ctx context.Context, symbol string, cat Category) ([]Filing, error)

Filings returns a company's regulatory filings.

func (*Client) FinancialAlert 

func (c *Client) FinancialAlert(ctx context.Context, symbol string, cat Category) (*FinancialAlert, error)

FinancialAlert returns the estimate for a company's next financial report.

func (*Client) FinancialIndicators 

func (c *Client) FinancialIndicators(ctx context.Context, req FinancialsRequest) (*FinancialIndicators, error)

FinancialIndicators returns a company's financial ratios per reporting period.

func (*Client) Footprints 

func (c *Client) Footprints(ctx context.Context, req FootprintsRequest) ([]Footprints, error)

Footprints returns footprint charts for each requested stock.

func (*Client) ForecastEPS 

func (c *Client) ForecastEPS(ctx context.Context, symbol string, cat Category) ([]EPSForecast, error)

ForecastEPS returns a stock's quarterly EPS estimates and results.

func (*Client) FundAllocations 

func (c *Client) FundAllocations(ctx context.Context, symbol string, cat Category) ([]FundAllocation, error)

FundAllocations returns a fund's asset allocation history.

func (*Client) FundBrief 

func (c *Client) FundBrief(ctx context.Context, symbol string, cat Category) (*FundBrief, error)

FundBrief returns a fund's profile.

func (*Client) FundDividends 

func (c *Client) FundDividends(ctx context.Context, symbol string, cat Category, paginationKey string) (*FundDividendsPage, error)

FundDividends returns a fund's distribution history. An empty paginationKey starts from the first page.

func (*Client) FundFiles 

func (c *Client) FundFiles(ctx context.Context, symbol string, cat Category) ([]FundFile, error)

FundFiles returns a fund's published documents.

func (*Client) FundHoldings 

func (c *Client) FundHoldings(ctx context.Context, symbol string, cat Category) ([]FundHolding, error)

FundHoldings returns a fund's largest positions.

func (*Client) FundNetValues 

func (c *Client) FundNetValues(ctx context.Context, symbol string, cat Category, lastDate time.Time, count int) ([]FundNetValue, error)

FundNetValues returns a fund's net asset value history, newest first, starting from lastDate when set. Count is between 1 and 20; zero lets Webull apply its default of 5.

func (*Client) FundPerformance 

func (c *Client) FundPerformance(ctx context.Context, symbol string, cat Category) (*FundPerformance, error)

FundPerformance returns a fund's trailing returns.

func (*Client) FundRatings 

func (c *Client) FundRatings(ctx context.Context, symbol string, cat Category) ([]FundRating, error)

FundRatings returns a fund's agency ratings.

func (*Client) FundSplits 

func (c *Client) FundSplits(ctx context.Context, symbol string, cat Category) ([]FundSplit, error)

FundSplits returns a fund's split history.

func (*Client) FuturesBars 

func (c *Client) FuturesBars(ctx context.Context, req AssetBarsRequest) ([]Bars, error)

FuturesBars returns candles for futures contracts.

func (*Client) FuturesDepth 

func (c *Client) FuturesDepth(ctx context.Context, symbol string, levels int) (*Depth, error)

FuturesDepth returns a futures contract's order book. Requires the FUTURES LV2 subscription; levels is how many price levels per side.

func (*Client) FuturesFootprints 

func (c *Client) FuturesFootprints(ctx context.Context, req FootprintsRequest) ([]Footprints, error)

FuturesFootprints returns footprint charts for futures contracts. Requires the FOOTPRINT subscription. req.Category is ignored: the futures endpoint takes only USFutures.

func (*Client) FuturesSnapshots 

func (c *Client) FuturesSnapshots(ctx context.Context, symbols []string) ([]FuturesSnapshot, error)

FuturesSnapshots returns the current state of up to 20 futures contracts.

func (*Client) FuturesTicks 

func (c *Client) FuturesTicks(ctx context.Context, symbol string, count int) (*AssetTicks, error)

FuturesTicks returns a futures contract's most recent trades. count is at most 1200; zero lets Webull apply its default.

func (*Client) GainersLosers 

func (c *Client) GainersLosers(ctx context.Context, req GainersLosersRequest) ([]ScreenerStock, error)

GainersLosers returns stocks ranked by price change.

func (*Client) HighDividend 

func (c *Client) HighDividend(ctx context.Context, req HighDividendRequest) ([]DividendStock, error)

HighDividend returns stocks ranked by dividend yield.

func (*Client) ImbalanceBars 

func (c *Client) ImbalanceBars(ctx context.Context, req ImbalanceRequest) ([]Imbalance, error)

ImbalanceBars returns the history of auction imbalance readings.

func (*Client) ImbalanceSnapshot 

func (c *Client) ImbalanceSnapshot(ctx context.Context, req ImbalanceRequest) (*ImbalanceSnapshot, error)

ImbalanceSnapshot returns the current auction imbalance.

func (*Client) IncomeStatements 

func (c *Client) IncomeStatements(ctx context.Context, req FinancialsRequest) ([]IncomeStatement, error)

IncomeStatements returns a company's income statements, most recent first.

func (*Client) IndustryComparison 

func (c *Client) IndustryComparison(ctx context.Context, symbol string, cat Category, metric ComparisonMetric) (*IndustryComparison, error)

IndustryComparison compares a company with its industry peers on one financial metric; an empty metric lets Webull default to EPSTTM.

func (*Client) MarketSectors 

func (c *Client) MarketSectors(ctx context.Context, req MarketSectorsRequest) (*SectorsPage, error)

MarketSectors returns market sectors ranked by the chosen aggregate.

func (*Client) OptionBars 

func (c *Client) OptionBars(ctx context.Context, req AssetBarsRequest) ([]Bars, error)

OptionBars returns candles for option contracts.

func (*Client) OptionSnapshots 

func (c *Client) OptionSnapshots(ctx context.Context, symbols []string) ([]OptionSnapshot, error)

OptionSnapshots returns the current state of up to 20 option contracts, identified by OCC symbol.

func (*Client) OptionTicks 

func (c *Client) OptionTicks(ctx context.Context, symbol string, count int) (*AssetTicks, error)

OptionTicks returns an option contract's most recent trades. count is at most 1200; zero lets Webull apply its default.

func (*Client) RemoveWatchlistInstruments 

func (c *Client) RemoveWatchlistInstruments(ctx context.Context, id string, entries []WatchlistEntry) error

RemoveWatchlistInstruments removes instruments from a watchlist.

func (*Client) SectorDetail 

func (c *Client) SectorDetail(ctx context.Context, req SectorDetailRequest) (*SectorDetail, error)

SectorDetail returns one sector's statistics and constituent stocks.

func (*Client) Snapshots 

func (c *Client) Snapshots(ctx context.Context, req SnapshotsRequest) ([]Snapshot, error)

Snapshots returns the current state of each requested stock.

Example

ExampleClient_Snapshots fetches the current state of two stocks, including the extended-hours session. 

package main

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

	"github.com/sfreiberg/webull"
	"github.com/sfreiberg/webull/marketdata"
)

func exampleClient() *webull.Client {
	client, err := webull.NewClient(webull.Config{
		AppKey:      os.Getenv("WEBULL_APP_KEY"),
		AppSecret:   os.Getenv("WEBULL_APP_SECRET"),
		Environment: webull.Sandbox,
	})
	if err != nil {
		log.Fatal(err)
	}
	return client
}

func main() {
	client := exampleClient()

	snaps, err := client.MarketData.Snapshots(context.Background(), marketdata.SnapshotsRequest{
		Symbols:       []string{"AAPL", "SPY"},
		ExtendedHours: true,
	})
	if err != nil {
		log.Fatal(err)
	}
	for _, s := range snaps {
		fmt.Println(s.Symbol, s.Price.Decimal, s.LastTradeTime)
	}
}

func (*Client) TargetPrice 

func (c *Client) TargetPrice(ctx context.Context, symbol string, cat Category) (*TargetPrice, error)

TargetPrice returns the consensus analyst price target for a stock.

func (*Client) Ticks 

func (c *Client) Ticks(ctx context.Context, req TicksRequest) (*Ticks, error)

Ticks returns a stock's most recent trades.

func (*Client) TopActive 

func (c *Client) TopActive(ctx context.Context, req TopActiveRequest) ([]ScreenerStock, error)

TopActive returns the most actively traded stocks.

func (*Client) UpdateWatchlist 

func (c *Client) UpdateWatchlist(ctx context.Context, id, name string, sort int) error

UpdateWatchlist renames or reorders a watchlist. An empty name or a zero sort leaves that attribute unchanged.

func (*Client) UpdateWatchlistInstruments 

func (c *Client) UpdateWatchlistInstruments(ctx context.Context, id string, entries []WatchlistEntry) error

UpdateWatchlistInstruments reorders instruments within a watchlist using each entry's Sort.

func (*Client) WatchlistInstruments 

func (c *Client) WatchlistInstruments(ctx context.Context, id string) ([]WatchlistInstrument, error)

WatchlistInstruments returns the instruments in a watchlist.

func (*Client) Watchlists 

func (c *Client) Watchlists(ctx context.Context) ([]Watchlist, error)

Watchlists returns the account's watchlists.

func (*Client) Week52HighLow 

func (c *Client) Week52HighLow(ctx context.Context, req Week52Request) ([]Week52Stock, error)

Week52HighLow returns stocks at or near their 52-week high or low.

type CompanyProfile 

type CompanyProfile struct {
	Symbol        string   `json:"symbol"`
	Category      Category `json:"category"`
	CompanyName   string   `json:"company_name"`
	EstablishDate string   `json:"establish_date"`
	Exchange      string   `json:"exhibition_code"`
	Profile       string   `json:"profile"`
	Employees     string   `json:"employees"`
	Address       string   `json:"address"`
	CEO           string   `json:"ceo"`
	Industries    []string `json:"industries"`
}

CompanyProfile describes a listed company.

type ComparisonMetric 

type ComparisonMetric string

ComparisonMetric is the financial metric an industry comparison ranks by. The values are Webull's IndustryComparisonSortBy dictionary. 

const (
	EPSTTM           ComparisonMetric = "EPS_TTM"
	NAPS             ComparisonMetric = "NAPS"
	DPSTTM           ComparisonMetric = "DPS_TTM"
	ROE              ComparisonMetric = "ROE"
	DebtToAssets     ComparisonMetric = "DEBT_TO_ASSETS"
	NetMargin        ComparisonMetric = "NET_MARGIN"
	DividendYieldTTM ComparisonMetric = "DIV_YIELD_TTM"
	PETTM            ComparisonMetric = "PE_TTM"
	PBRatio          ComparisonMetric = "PB_RATIO"
)

Comparison metrics.

type CryptoSnapshot 

type CryptoSnapshot struct {
	Symbol       string `json:"symbol"`
	InstrumentID string `json:"instrument_id"`

	Price         NullDecimal `json:"price"`
	Open          NullDecimal `json:"open"`
	High          NullDecimal `json:"high"`
	Low           NullDecimal `json:"low"`
	Close         NullDecimal `json:"close"`
	PreClose      NullDecimal `json:"pre_close"`
	Change        NullDecimal `json:"change"`
	ChangeRatio   NullDecimal `json:"change_ratio"`
	LastTradeTime Millis      `json:"last_trade_time"`

	Bid       NullDecimal `json:"bid"`
	BidSize   NullDecimal `json:"bid_size"`
	Ask       NullDecimal `json:"ask"`
	AskSize   NullDecimal `json:"ask_size"`
	QuoteTime Millis      `json:"quote_time"`
}

CryptoSnapshot is the current state of a crypto pair. Sizes are in coins and may carry up to eight decimal places.

type Decimal 

type Decimal = wire.Decimal

Decimal is the SDK's fixed-point decimal type. It embeds github.com/shopspring/decimal.Decimal, so all of that type's methods are available, and additionally decodes Webull's absent forms — null and an empty string — where shopspring's own type rejects "".

type Depth 

type Depth struct {
	Symbol       string  `json:"symbol"`
	InstrumentID string  `json:"instrument_id"`
	QuoteTime    Millis  `json:"quote_time"`
	Asks         []Level `json:"asks"`
	Bids         []Level `json:"bids"`
}

Depth is the order book for one stock.

type DepthRequest 

type DepthRequest struct {
	Symbol   string
	Category Category
	// Levels is how many price levels to return. Webull rejects a number
	// beyond the key's entitlement: a key with Level 1 data may ask for one.
	// Zero lets Webull apply its default.
	Levels    int
	Overnight bool
}

DepthRequest selects a stock's order book.

type Dividend 

type Dividend struct {
	Symbol         string  `json:"symbol"`
	Market         string  `json:"market"`
	Currency       string  `json:"currency"`
	Amount         Decimal `json:"amount"`
	Type           string  `json:"div_type"`
	DeclareDate    Time    `json:"declare_date"`
	ExDividendDate Time    `json:"ex_div_date"`
	RecordDate     Time    `json:"record_date"`
	PayDate        Time    `json:"pay_date"`
}

Dividend is one declared dividend.

type DividendStock 

type DividendStock struct {
	InstrumentID string      `json:"instrument_id"`
	Category     Category    `json:"category"`
	Symbol       string      `json:"symbol"`
	Name         string      `json:"name"`
	ExchangeCode string      `json:"exchange_code"`
	Currency     string      `json:"currency"`
	Close        NullDecimal `json:"close"`
	Change       NullDecimal `json:"change"`
	ChangeRatio  NullDecimal `json:"change_ratio"`
	Price        NullDecimal `json:"price"`
	Volume       NullDecimal `json:"volume"`
	MarketValue  NullDecimal `json:"market_value"`
	TurnoverRate NullDecimal `json:"turnover_rate"`
	Amplitude    NullDecimal `json:"amplitude"`
	High         NullDecimal `json:"high"`
	Low          NullDecimal `json:"low"`
	Turnover     NullDecimal `json:"turnover"`
	Yield        NullDecimal `json:"yield"`
	Dividend     NullDecimal `json:"dividend"`
	ExDate       Time        `json:"ex_date"`
	PETTM        NullDecimal `json:"pe_ttm"`
}

DividendStock is one row of the high-dividend screener.

type EPSForecast 

type EPSForecast struct {
	FiscalYear   int         `json:"fiscal_year"`
	FiscalPeriod int         `json:"fiscal_period"`
	Actual       NullDecimal `json:"actual"`
	Estimate     NullDecimal `json:"est"`
	Reported     bool        `json:"reported"`
}

EPSForecast is one quarter's estimated and, once reported, actual EPS.

type Earnings 

type Earnings struct {
	FiscalYear          int         `json:"fiscal_year"`
	FiscalPeriod        int         `json:"fiscal_period"`
	Currency            string      `json:"currency"`
	ExpectedPublishDate Time        `json:"expected_publish_date"`
	EPSActual           NullDecimal `json:"eps_actual"`
	EPSEstimate         NullDecimal `json:"eps_est"`
	RevenueActual       NullDecimal `json:"rev_actual"`
	RevenueEstimate     NullDecimal `json:"rev_est"`
}

Earnings is one quarter's estimated and, once reported, actual earnings.

type EventDepth 

type EventDepth struct {
	Symbol       string  `json:"symbol"`
	InstrumentID string  `json:"instrument_id"`
	QuoteTime    Millis  `json:"quote_time"`
	YesBids      []Level `json:"yes_bids"`
	YesAsks      []Level `json:"yes_asks"`
	NoBids       []Level `json:"no_bids"`
	NoAsks       []Level `json:"no_asks"`
}

EventDepth is the order book of an event contract market, one book per outcome. Sides with no orders are absent or empty.

type EventOutcome 

type EventOutcome string

EventOutcome is the side of an event contract trade. It carries the same wire values as trade.EventOutcome; the two packages do not import each other, so each declares its own. 

const (
	OutcomeYes EventOutcome = "yes"
	OutcomeNo  EventOutcome = "no"
)

Event outcomes.

type EventSnapshot 

type EventSnapshot struct {
	Symbol       string `json:"symbol"`
	InstrumentID string `json:"instrument_id"`
	Name         string `json:"name"`

	Price         NullDecimal `json:"price"`
	Volume        NullDecimal `json:"volume"`
	OpenInterest  NullDecimal `json:"open_interest"`
	LastTradeTime Millis      `json:"last_trade_time"`

	YesBid     NullDecimal `json:"yes_bid"`
	YesBidSize NullDecimal `json:"yes_bid_size"`
	YesAsk     NullDecimal `json:"yes_ask"`
	YesAskSize NullDecimal `json:"yes_ask_size"`
	NoBid      NullDecimal `json:"no_bid"`
	NoBidSize  NullDecimal `json:"no_bid_size"`
	NoAsk      NullDecimal `json:"no_ask"`
	NoAskSize  NullDecimal `json:"no_ask_size"`
}

EventSnapshot is the current state of an event contract market: a binary contract with a yes side and a no side.

type EventTick 

type EventTick struct {
	Time     Millis       `json:"time"`
	TradeID  string       `json:"trade_id"`
	Side     EventOutcome `json:"side"`
	YesPrice Decimal      `json:"yes_price"`
	NoPrice  Decimal      `json:"no_price"`
	Volume   Decimal      `json:"volume"`
}

EventTick is one event contract trade, reported with both outcomes' prices.

type EventTicks 

type EventTicks struct {
	Symbol       string      `json:"symbol"`
	InstrumentID string      `json:"instrument_id"`
	Ticks        []EventTick `json:"result"`
}

EventTicks is an event contract market's recent trades, newest first.

type Filing 

type Filing struct {
	Title       string `json:"title"`
	URL         string `json:"url"`
	PublishDate Time   `json:"publish_date"`
}

Filing is one regulatory filing.

type FinancialAlert 

type FinancialAlert struct {
	// StartDate and EndDate bound the expected publication window.
	StartDate  Time `json:"start_date"`
	EndDate    Time `json:"end_date"`
	FiscalYear int  `json:"fiscal_year"`
	// FiscalPeriod is 1 through 4 for quarters, or 5 for a pre-release.
	FiscalPeriod    int         `json:"fiscal_period"`
	Currency        string      `json:"currency"`
	EPSEstimate     NullDecimal `json:"eps_est"`
	EPSLastYear     NullDecimal `json:"eps_ly"`
	RevenueEstimate NullDecimal `json:"rev_est"`
	RevenueLastYear NullDecimal `json:"rev_ly"`
}

FinancialAlert is the estimate for a company's next financial report and the window in which it is expected.

type FinancialIndicators 

type FinancialIndicators struct {
	Currency string                      `json:"currency"`
	Values   map[string][]IndicatorValue `json:"values"`
}

FinancialIndicators holds per-period financial ratios keyed by indicator name. The documented keys are roa, roe, diluted_eps_incl_extra, net_margin, debt_to_assets, naps, ocf_ps and cap_surplus_ps.

type FinancialType 

type FinancialType string

FinancialType selects annual or quarterly financial reports. 

const (
	Annual    FinancialType = "ANNUAL"
	Quarterly FinancialType = "QUARTERLY"
)

Financial report types.

type FinancialsRequest 

type FinancialsRequest struct {
	Symbol string
	// Category defaults to USStock, the only documented value.
	Category Category
	// Type is Annual or Quarterly; empty lets Webull default to Quarterly.
	Type FinancialType
	// Count is between 1 and 20; zero lets Webull apply its default of 5.
	Count int
}

FinancialsRequest selects a company's financial reports.

type Footprint 

type Footprint struct {
	Time      Time           `json:"time"`
	Session   TradingSession `json:"trading_session"`
	Total     Decimal        `json:"total"`
	Delta     Decimal        `json:"delta"`
	BuyTotal  Decimal        `json:"buy_total"`
	SellTotal Decimal        `json:"sell_total"`
	// BuyDetail and SellDetail map price to volume.
	BuyDetail  map[string]Decimal `json:"buy_detail"`
	SellDetail map[string]Decimal `json:"sell_detail"`
}

Footprint is one interval's traded volume broken down by price and side.

type Footprints 

type Footprints struct {
	Symbol       string      `json:"symbol"`
	InstrumentID string      `json:"instrument_id"`
	Footprints   []Footprint `json:"result"`
}

Footprints is one stock's footprint chart.

type FootprintsRequest 

type FootprintsRequest struct {
	Symbols []string
	// Category applies to Footprints only; FuturesFootprints ignores it.
	Category Category
	// Timespan is one of Second5, Second15, Minute, Minute5 or Minute30.
	Timespan Timespan
	// Count is at most 1200; zero lets Webull apply its default of 200.
	Count int
	// Completed omits the interval still forming.
	Completed bool
	// Session selects one session; Overnight is not supported.
	Session TradingSession
}

FootprintsRequest selects footprint data. Requires the FOOTPRINT subscription.

type FundAllocation 

type FundAllocation struct {
	Date        Time        `json:"date"`
	AUM         NullDecimal `json:"aum"`
	Cash        FundAsset   `json:"cash"`
	Bond        FundAsset   `json:"bond"`
	Stock       FundAsset   `json:"stock"`
	Preferred   FundAsset   `json:"preferred"`
	Convertible FundAsset   `json:"convertible"`
	Other       FundAsset   `json:"other"`
}

FundAllocation is a fund's portfolio broken down by asset class on one reporting date.

type FundAsset 

type FundAsset struct {
	Value NullDecimal `json:"value"`
	Ratio NullDecimal `json:"ratio"`
}

FundAsset is one asset class's share of a fund's portfolio.

type FundBrief 

type FundBrief struct {
	Name                string        `json:"name"`
	LaunchDate          Time          `json:"launch_date"`
	Benchmark           string        `json:"benchmark"`
	InvestmentObjective string        `json:"investment_objective"`
	AUM                 NullDecimal   `json:"aum"`
	Issuer              string        `json:"issuer"`
	Custodian           string        `json:"custodian"`
	Managers            []FundManager `json:"managers"`
}

FundBrief describes a fund: objective, benchmark, size and management.

type FundDividend 

type FundDividend struct {
	DeclareDate    Time    `json:"publish_date"`
	ExDividendDate Time    `json:"share_date"`
	RecordDate     Time    `json:"record_date"`
	PayDate        Time    `json:"pay_date"`
	PerShare       Decimal `json:"dps"`
}

FundDividend is one distribution by a fund.

type FundDividendsPage 

type FundDividendsPage struct {
	Dividends []FundDividend `json:"data"`
	// PaginationKey continues the listing; empty on the last page.
	PaginationKey string `json:"pagination_key"`
}

FundDividendsPage is one page of fund distributions.

type FundFile 

type FundFile struct {
	Name        string `json:"file_name"`
	URL         string `json:"url"`
	PublishDate Time   `json:"publish_date"`
	// Type is Webull's document-type code: 1 prospectus, 4 annual report,
	// 5 semi-annual report, 14 quarterly report, 17 prospectus summary.
	Type int `json:"type"`
}

FundFile is one fund document, such as a prospectus or annual report.

type FundHolding 

type FundHolding struct {
	Symbol            string      `json:"target_symbol"`
	Name              string      `json:"stock_name"`
	HeldPercent       NullDecimal `json:"share_held_pct"`
	HeldChangePercent NullDecimal `json:"share_held_chg_pct"`
	MaturityDate      Time        `json:"maturity_date"`
	UpdateTime        Time        `json:"update_time"`
}

FundHolding is one position in a fund's portfolio.

type FundManager 

type FundManager struct {
	Name      string `json:"name"`
	Title     string `json:"title"`
	StartDate Time   `json:"start_date"`
	EndDate   Time   `json:"end_date"`
	// Incumbent is 1 while the manager is in post.
	Incumbent    int         `json:"is_incumbent"`
	TenureReturn NullDecimal `json:"tenure_return"`
	TenureYears  NullDecimal `json:"tenure_years"`
	TenureDays   int         `json:"tenure_days"`
}

FundManager is one manager's tenure at a fund.

type FundNetValue 

type FundNetValue struct {
	Date     Time    `json:"date"`
	Currency string  `json:"currency"`
	NetValue Decimal `json:"net_value"`
}

FundNetValue is a fund's net asset value on one date.

type FundPerformance 

type FundPerformance struct {
	Currency       string      `json:"currency"`
	EndDate        Time        `json:"end_date"`
	Return1M       NullDecimal `json:"return_1m"`
	Return3M       NullDecimal `json:"return_3m"`
	Return6M       NullDecimal `json:"return_6m"`
	Return1Y       NullDecimal `json:"return_1y"`
	Return3Y       NullDecimal `json:"return_3y"`
	Return5Y       NullDecimal `json:"return_5y"`
	Return10Y      NullDecimal `json:"return_10y"`
	SinceInception NullDecimal `json:"return_si"`
}

FundPerformance is a fund's trailing returns, as percentages.

type FundRating 

type FundRating struct {
	Date   Time   `json:"rating_date"`
	Agency string `json:"rating_agency"`
	// Cycle is the period rated: "0" since establishment, or "3", "5" or
	// "10" years.
	Cycle string `json:"rating_cycle"`
	// Rating is 1 (low) through 5 (high).
	Rating int `json:"rating_results"`
}

FundRating is one agency's rating of a fund.

type FundSplit 

type FundSplit struct {
	Date Time `json:"split_date"`
	// Type is "SPLIT" or "MERGE".
	Type  string  `json:"split_type"`
	Ratio string  `json:"split_ratio"`
	From  Decimal `json:"from"`
	To    Decimal `json:"to"`
}

FundSplit is one share split or merge by a fund.

type FuturesSnapshot 

type FuturesSnapshot struct {
	Symbol       string `json:"symbol"`
	InstrumentID string `json:"instrument_id"`

	Price         NullDecimal `json:"price"`
	Open          NullDecimal `json:"open"`
	High          NullDecimal `json:"high"`
	Low           NullDecimal `json:"low"`
	PreClose      NullDecimal `json:"pre_close"`
	Volume        NullDecimal `json:"volume"`
	Change        NullDecimal `json:"change"`
	ChangeRatio   NullDecimal `json:"change_ratio"`
	LastTradeTime Millis      `json:"last_trade_time"`

	Bid       NullDecimal `json:"bid"`
	BidSize   NullDecimal `json:"bid_size"`
	Ask       NullDecimal `json:"ask"`
	AskSize   NullDecimal `json:"ask_size"`
	QuoteTime Millis      `json:"quote_time"`

	OpenInterest NullDecimal `json:"open_interest"`
	SettlePrice  NullDecimal `json:"settle_price"`
	SettleDate   Time        `json:"settle_date"`
}

FuturesSnapshot is the current state of a futures contract.

The sandbox serves futures market data for a single symbol, "MESmain", the continuous Micro E-mini S&P 500; every other symbol is rejected with "Only these symbols are supported". A snapshot for a continuous symbol reports the resolved contract, such as "MESU6", in Symbol.

type GainersLosersRequest 

type GainersLosersRequest struct {
	// Period is the change window; the server default is Rank1Day.
	Period RankPeriod
	// Category defaults to USStock.
	Category Category
	// SortBy defaults to SortChangeRatio on the server.
	SortBy ScreenerSort
	// Direction defaults to Descending, which ranks gainers; Ascending
	// ranks losers.
	Direction SortDirection
}

GainersLosersRequest selects a price-change ranking.

type HighDividendRequest 

type HighDividendRequest struct {
	// Category defaults to USStock.
	Category Category
	// SortBy defaults to SortYield on the server.
	SortBy ScreenerSort
	// Direction defaults to Descending on the server.
	Direction SortDirection
}

HighDividendRequest selects a dividend-yield ranking.

type Imbalance 

type Imbalance struct {
	Symbol       string        `json:"symbol"`
	InstrumentID string        `json:"instrument_id"`
	Time         Millis        `json:"imbalance_time"`
	Type         ImbalanceType `json:"imbalance_action_type"`
	RefPrice     Decimal       `json:"imbalance_ref_price"`
	NearPrice    Decimal       `json:"imbalance_near_price"`
	FarPrice     Decimal       `json:"imbalance_far_price"`
}

Imbalance is one auction imbalance reading.

type ImbalanceRequest 

type ImbalanceRequest struct {
	Symbol   string
	Category Category
	Type     ImbalanceType
}

ImbalanceRequest selects a stock's opening or closing auction imbalance. Requires the STOCK QUOTES LV2 subscription.

type ImbalanceSnapshot 

type ImbalanceSnapshot struct {
	Imbalance
	PairedShares    Decimal `json:"paired_shares"`
	ImbalanceShares Decimal `json:"imbalance_shares"`
	Side            string  `json:"imbalance_side"`
	VarIndicator    string  `json:"imbalance_var_indicator"`
}

ImbalanceSnapshot is the current auction imbalance for a stock.

type ImbalanceType 

type ImbalanceType string

ImbalanceType selects the opening or closing auction imbalance. 

const (
	PreOpen  ImbalanceType = "PRE_OPEN"
	PreClose ImbalanceType = "PRE_CLOSE"
)

Imbalance types.

type IncomeStatement 

type IncomeStatement struct {
	ReportPeriod

	TotalRevenue             NullDecimal `json:"total_revenue"`
	Revenue                  NullDecimal `json:"revenue"`
	CostOfRevenue            NullDecimal `json:"cost_of_revenue"`
	GrossProfit              NullDecimal `json:"gross_profit"`
	OperatingExpenses        NullDecimal `json:"opex"`
	SGAExpenses              NullDecimal `json:"sga_exp"`
	RnDExpenses              NullDecimal `json:"rnd_exp"`
	UnusualExpenseIncome     NullDecimal `json:"unusual_expense_income"`
	OperatingIncome          NullDecimal `json:"op_income"`
	OperatingProfit          NullDecimal `json:"op_profit"`
	NonOperatingInterestNet  NullDecimal `json:"inter_inc_expse_net_non_oper"`
	GainOnSaleOfAssets       NullDecimal `json:"gain_loss_on_sale_of_assets"`
	OtherNetIncome           NullDecimal `json:"other_net_income"`
	PretaxIncome             NullDecimal `json:"ebt"`
	PretaxEarnings           NullDecimal `json:"ebt_alt"`
	IncomeTax                NullDecimal `json:"income_tax"`
	AfterTaxIncome           NullDecimal `json:"eat"`
	AfterTaxEarnings         NullDecimal `json:"eat_alt"`
	MinorityInterest         NullDecimal `json:"minority_interest"`
	IncomeBeforeExtraItems   NullDecimal `json:"ni_pre_extra"`
	ExtraordinaryItems       NullDecimal `json:"extra_items"`
	NetIncome                NullDecimal `json:"net_income"`
	NetIncomeCommonExclExtra NullDecimal `json:"ni_common_excl_extra"`
	NetIncomeCommonInclExtra NullDecimal `json:"ni_common_incl_extra"`
	DilutedNetIncome         NullDecimal `json:"diluted_ni"`
	DilutedAvgShares         NullDecimal `json:"diluted_avg_shares"`
	DilutedEPSExclExtra      NullDecimal `json:"diluted_eps_excl_extra"`
	DilutedEPSInclExtra      NullDecimal `json:"diluted_eps_incl_extra"`
	DilutedNormalizedEPS     NullDecimal `json:"diluted_norm_eps"`
	DividendsPerShare        NullDecimal `json:"dps"`
}

IncomeStatement is one reporting period's income statement. Line items a company does not report are null.

type IndicatorValue 

type IndicatorValue struct {
	FiscalYear int `json:"fiscal_year"`
	// FiscalPeriod is 0 for the full year and 1 through 4 for quarters.
	FiscalPeriod int         `json:"fiscal_period"`
	Value        NullDecimal `json:"value"`
}

IndicatorValue is one reporting period's value of a financial indicator. Value is null when Webull has no figure for the period.

type IndustryComparison 

type IndustryComparison struct {
	FiscalYear   int              `json:"fiscal_year"`
	FiscalPeriod int              `json:"fiscal_period"`
	IndustryName string           `json:"industry_name"`
	Metric       ComparisonMetric `json:"type"`
	Companies    []IndustryRank   `json:"data"`
}

IndustryComparison ranks a company's industry peers on one metric.

type IndustryRank 

type IndustryRank struct {
	Symbol string      `json:"symbol"`
	Name   string      `json:"name"`
	Rank   int         `json:"rank"`
	Value  NullDecimal `json:"value"`
}

IndustryRank is one company's rank within its industry on the compared metric. Value is null when the company has no figure for the metric.

type Level 

type Level struct {
	Price  Decimal       `json:"price"`
	Size   Decimal       `json:"size"`
	Orders []LevelOrder  `json:"order,omitempty"`
	Broker []LevelBroker `json:"broker,omitempty"`
}

Level is one price level of the book. Order and Broker breakdowns are present only at depths the key is entitled to.

type LevelBroker 

type LevelBroker struct {
	ID   string `json:"bid"`
	Name string `json:"name"`
}

LevelBroker identifies a broker at a level.

type LevelOrder 

type LevelOrder struct {
	MPID string  `json:"mpid"`
	Size Decimal `json:"size"`
}

LevelOrder is one market participant's size at a level.

type MarketSectorsRequest 

type MarketSectorsRequest struct {
	// Category defaults to USStock.
	Category Category
	// Aggregate defaults to SectorMarketValue on the server.
	Aggregate SectorAggregate
	// Period defaults to Sector1Day on the server.
	Period    SectorPeriod
	Direction SortDirection
	// PaginationKey continues a previous page. Leave empty for the first.
	PaginationKey string
}

MarketSectorsRequest selects a sector ranking.

type Millis 

type Millis = wire.Millis

Millis is a point in time transmitted as epoch milliseconds, which Webull sends sometimes as a JSON number and sometimes as a string. The zero value means the field was absent; a wire value of 0 is treated the same way, since no market data event happened at the epoch. It is an alias of the shared wire type also used by the root package.

type NullDecimal 

type NullDecimal = wire.NullDecimal

NullDecimal is the SDK's nullable fixed-point decimal type, the counterpart of Decimal for fields that may be absent.

type OptionSnapshot 

type OptionSnapshot struct {
	Symbol       string `json:"symbol"`
	InstrumentID string `json:"instrument_id"`

	Price         NullDecimal `json:"price"`
	Open          NullDecimal `json:"open"`
	High          NullDecimal `json:"high"`
	Low           NullDecimal `json:"low"`
	Close         NullDecimal `json:"close"`
	PreClose      NullDecimal `json:"pre_close"`
	Volume        NullDecimal `json:"volume"`
	Change        NullDecimal `json:"change"`
	ChangeRatio   NullDecimal `json:"change_ratio"`
	LastTradeTime Millis      `json:"last_trade_time"`

	Bid       NullDecimal `json:"bid"`
	BidSize   NullDecimal `json:"bid_size"`
	Ask       NullDecimal `json:"ask"`
	AskSize   NullDecimal `json:"ask_size"`
	QuoteTime Millis      `json:"quote_time"`

	StrikePrice  NullDecimal `json:"strike_price"`
	OpenInterest NullDecimal `json:"open_interest"`
	// DealAmount is the day's traded value; returned by the API but not
	// documented.
	DealAmount NullDecimal `json:"deal_amount"`

	Delta      NullDecimal `json:"delta"`
	Gamma      NullDecimal `json:"gamma"`
	Theta      NullDecimal `json:"theta"`
	Vega       NullDecimal `json:"vega"`
	Rho        NullDecimal `json:"rho"`
	ImpliedVol NullDecimal `json:"imp_vol"`
}

OptionSnapshot is the current state of an option contract, including its greeks and implied volatility.

type RankPeriod 

type RankPeriod string

RankPeriod is the time window a gainers-losers ranking is computed over. 

const (
	RankPreMarket   RankPeriod = "PRE_MARKET"
	RankAfterMarket RankPeriod = "AFTER_MARKET"
	Rank3Min        RankPeriod = "MIN_3"
	Rank5Min        RankPeriod = "MIN_5"
	Rank1Day        RankPeriod = "DAY_1"
	Rank5Day        RankPeriod = "DAY_5"
	Rank1Month      RankPeriod = "MONTH_1"
	Rank3Month      RankPeriod = "MONTH_3"
	Rank52Week      RankPeriod = "WEEK_52"
)

Ranking periods.

type ReportPeriod 

type ReportPeriod struct {
	FiscalYear int `json:"fiscal_year"`
	// FiscalPeriod is 0 for the full year and 1 through 4 for quarters.
	FiscalPeriod int    `json:"fiscal_period"`
	EndDate      Time   `json:"end_date"`
	PublishDate  Time   `json:"publish_date"`
	Currency     string `json:"currency"`
}

ReportPeriod identifies the reporting period of a financial statement.

type ScreenerSort 

type ScreenerSort string

ScreenerSort is the field a screener ranking is ordered by. 

const (
	SortChangeRatio    ScreenerSort = "CHANGE_RATIO"
	SortRelativeVolume ScreenerSort = "RELATIVE_VOLUME_10D"
	SortMarketValue    ScreenerSort = "MARKET_VALUE"
	SortClose          ScreenerSort = "CLOSE"
	SortPrice          ScreenerSort = "PRICE"
	SortPETTM          ScreenerSort = "PE_TTM"
	SortHigh           ScreenerSort = "HIGH"
	SortLow            ScreenerSort = "LOW"
	SortAmplitude      ScreenerSort = "AMPLITUDE"
	SortTurnover       ScreenerSort = "TURNOVER"
	SortVolume         ScreenerSort = "VOLUME"
	SortYield          ScreenerSort = "YIELD"
	SortDividend       ScreenerSort = "DIVIDEND"
	// SortChangeRatio52W is the 52-week screener's server default: the
	// change since the 52-week extreme rather than the daily change.
	SortChangeRatio52W ScreenerSort = "CHANGE_RATIO_52W"
)

Screener sort fields. Yield and Dividend apply to the high-dividend screener only.

type ScreenerStock 

type ScreenerStock struct {
	InstrumentID   string      `json:"instrument_id"`
	Symbol         string      `json:"symbol"`
	Name           string      `json:"name"`
	ExchangeCode   string      `json:"exchange_code"`
	CurrencyCode   string      `json:"currency_code"`
	Currency       string      `json:"currency"`
	PreClose       NullDecimal `json:"pre_close"`
	Open           NullDecimal `json:"open"`
	High           NullDecimal `json:"high"`
	Low            NullDecimal `json:"low"`
	Close          NullDecimal `json:"close"`
	Price          NullDecimal `json:"price"`
	Change         NullDecimal `json:"change"`
	ChangeRatio    NullDecimal `json:"change_ratio"`
	Volume         NullDecimal `json:"volume"`
	Turnover       NullDecimal `json:"turnover"`
	TurnoverRate   NullDecimal `json:"turnover_rate"`
	MarketValue    NullDecimal `json:"market_value"`
	Amplitude      NullDecimal `json:"amplitude"`
	RelativeVolume NullDecimal `json:"relative_volume_10d"`
	PETTM          NullDecimal `json:"pe_ttm"`
}

ScreenerStock is one row of the gainers-losers or top-active screener.

Turnover is null for US-market keys without the entitlement Webull calls "Nb authorization"; Currency and PETTM are returned but not documented.

type Sector 

type Sector struct {
	ID          string         `json:"id"`
	Name        string         `json:"name"`
	ChangeRatio NullDecimal    `json:"change_ratio"`
	Volume      NullDecimal    `json:"volume"`
	MarketValue NullDecimal    `json:"market_value"`
	Declined    NullDecimal    `json:"declined"`
	Advanced    NullDecimal    `json:"advanced"`
	Flat        NullDecimal    `json:"flat"`
	Leaders     []SectorLeader `json:"data"`
}

Sector is one market sector's aggregate statistics.

type SectorAggregate 

type SectorAggregate string

SectorAggregate is the statistic sectors are ranked by. 

const (
	SectorMarketValue SectorAggregate = "MARKET_VALUE"
	SectorVolume      SectorAggregate = "VOLUME"
)

Sector aggregates.

type SectorDetail 

type SectorDetail struct {
	ID          string        `json:"id"`
	Name        string        `json:"name"`
	ChangeRatio NullDecimal   `json:"change_ratio"`
	Declined    NullDecimal   `json:"declined"`
	Advanced    NullDecimal   `json:"advanced"`
	Flat        NullDecimal   `json:"flat"`
	Stocks      []SectorStock `json:"data"`
	// PaginationKey continues the stock listing; empty on the last page.
	PaginationKey string `json:"pagination_key"`
}

SectorDetail is one sector's statistics with its constituent stocks.

type SectorDetailRequest 

type SectorDetailRequest struct {
	// SectorID comes from MarketSectors.
	SectorID string
	// Category defaults to USStock.
	Category Category
	// Period defaults to Sector1Day on the server.
	Period SectorPeriod
	// SortBy defaults to SortChangeRatio on the server.
	SortBy    ScreenerSort
	Direction SortDirection
	// PaginationKey continues a previous page. Leave empty for the first.
	PaginationKey string
}

SectorDetailRequest selects one sector's constituents.

type SectorLeader 

type SectorLeader struct {
	InstrumentID string `json:"instrument_id"`
	Symbol       string `json:"symbol"`
	Name         string `json:"name"`
}

SectorLeader is a leading stock within a sector.

type SectorPeriod 

type SectorPeriod string

SectorPeriod is the window sector statistics are computed over. 

const (
	Sector1Day   SectorPeriod = "D1"
	Sector5Day   SectorPeriod = "D5"
	Sector1Month SectorPeriod = "MO1"
	Sector3Month SectorPeriod = "MO3"
)

Sector statistics periods.

type SectorStock 

type SectorStock struct {
	InstrumentID string      `json:"instrument_id"`
	Category     Category    `json:"category"`
	Symbol       string      `json:"symbol"`
	Name         string      `json:"name"`
	ExchangeCode string      `json:"exchange_code"`
	Currency     string      `json:"currency"`
	Close        NullDecimal `json:"close"`
	ChangeRatio  NullDecimal `json:"change_ratio"`
	Price        NullDecimal `json:"price"`
	Volume       NullDecimal `json:"volume"`
	MarketValue  NullDecimal `json:"market_value"`
	TurnoverRate NullDecimal `json:"turnover_rate"`
	Amplitude    NullDecimal `json:"amplitude"`
	High         NullDecimal `json:"high"`
	Low          NullDecimal `json:"low"`
}

SectorStock is one stock within a sector detail listing.

type SectorsPage 

type SectorsPage struct {
	Sectors []Sector `json:"data"`
	// PaginationKey continues the listing; empty on the last page.
	PaginationKey string `json:"pagination_key"`
}

SectorsPage is one page of market sectors.

func (*SectorsPage) UnmarshalJSON 

func (p *SectorsPage) UnmarshalJSON(b []byte) error

UnmarshalJSON accepts the {"data": [...], "pagination_key": ...} envelope the sandbox returns, or the bare array Webull's formatter documentation describes, which cannot paginate.

type Snapshot 

type Snapshot struct {
	Symbol       string `json:"symbol"`
	InstrumentID string `json:"instrument_id"`

	Price         NullDecimal `json:"price"`
	Open          NullDecimal `json:"open"`
	High          NullDecimal `json:"high"`
	Low           NullDecimal `json:"low"`
	Close         NullDecimal `json:"close"`
	PreClose      NullDecimal `json:"pre_close"`
	Volume        NullDecimal `json:"volume"`
	Change        NullDecimal `json:"change"`
	ChangeRatio   NullDecimal `json:"change_ratio"`
	LastTradeTime Millis      `json:"last_trade_time"`

	Ask       NullDecimal `json:"ask"`
	AskSize   NullDecimal `json:"ask_size"`
	Bid       NullDecimal `json:"bid"`
	BidSize   NullDecimal `json:"bid_size"`
	QuoteTime Millis      `json:"quote_time"`

	Turnover NullDecimal `json:"turnover"`
	EPS      NullDecimal `json:"eps"`
	EPSTTM   NullDecimal `json:"eps_ttm"`
	LotSize  NullDecimal `json:"lot_size"`
	BPS      NullDecimal `json:"bps"`

	// Valuation and share-count fields are returned by the API but not
	// documented.
	PERatio           NullDecimal `json:"pe_ratio"`
	PBRatio           NullDecimal `json:"pb_ratio"`
	PSRatio           NullDecimal `json:"ps_ratio"`
	Yield             NullDecimal `json:"yield"`
	MarketValue       NullDecimal `json:"market_value"`
	NegMarketValue    NullDecimal `json:"neg_market_value"`
	TotalShares       NullDecimal `json:"total_shares"`
	OutstandingShares NullDecimal `json:"out_standing_shares"`
	FiftyTwoWeekHigh  NullDecimal `json:"fifty_two_wk_high"`
	FiftyTwoWeekLow   NullDecimal `json:"fifty_two_wk_low"`
	ListStatus        string      `json:"list_status"`

	// Extended hours, populated when SnapshotsRequest.ExtendedHours is set.
	ExtendedLastPrice     NullDecimal `json:"extend_hour_last_price"`
	ExtendedHigh          NullDecimal `json:"extend_hour_high"`
	ExtendedLow           NullDecimal `json:"extend_hour_low"`
	ExtendedChange        NullDecimal `json:"extend_hour_change"`
	ExtendedChangeRatio   NullDecimal `json:"extend_hour_change_ratio"`
	ExtendedVolume        NullDecimal `json:"extend_hour_volume"`
	ExtendedLastTradeTime Millis      `json:"extend_hour_last_trade_time"`

	// Overnight session, populated when SnapshotsRequest.Overnight is set.
	OvernightPrice         NullDecimal `json:"ovn_price"`
	OvernightHigh          NullDecimal `json:"ovn_high"`
	OvernightLow           NullDecimal `json:"ovn_low"`
	OvernightVolume        NullDecimal `json:"ovn_volume"`
	OvernightChange        NullDecimal `json:"ovn_change"`
	OvernightChangeRatio   NullDecimal `json:"ovn_change_ratio"`
	OvernightLastTradeTime Millis      `json:"ovn_last_trade_time"`
	OvernightAsk           NullDecimal `json:"ovn_ask"`
	OvernightAskSize       NullDecimal `json:"ovn_ask_size"`
	OvernightBid           NullDecimal `json:"ovn_bid"`
	OvernightBidSize       NullDecimal `json:"ovn_bid_size"`
	OvernightQuoteTime     Millis      `json:"ovn_quote_time"`
}

Snapshot is the current state of a stock: last trade, top of book, the day's range and, when requested, extended-hours and overnight sessions.

Most fields are NullDecimal because Webull omits them when there has been no trading in the relevant session.

type SnapshotsRequest 

type SnapshotsRequest struct {
	// Symbols holds up to 100 symbols.
	Symbols []string
	// Category defaults to USStock.
	Category Category
	// ExtendedHours and Overnight include those sessions' fields.
	ExtendedHours bool
	Overnight     bool
}

SnapshotsRequest selects the stocks to snapshot.

type SortDirection 

type SortDirection string

SortDirection orders a ranking. 

const (
	Ascending  SortDirection = "ASC"
	Descending SortDirection = "DESC"
)

Sort directions.

type TargetPrice 

type TargetPrice struct {
	Symbol        string   `json:"symbol"`
	Category      Category `json:"category"`
	Mean          Decimal  `json:"mean"`
	Median        Decimal  `json:"median"`
	Low           Decimal  `json:"low"`
	High          Decimal  `json:"high"`
	Currency      string   `json:"currency"`
	EffectiveFrom Time     `json:"effective_start_date"`
}

TargetPrice is the consensus of analyst price targets.

type Tick 

type Tick struct {
	Time    Millis         `json:"time"`
	Price   Decimal        `json:"price"`
	Volume  Decimal        `json:"volume"`
	Side    TickSide       `json:"side"`
	Session TradingSession `json:"trading_session"`
}

Tick is one trade.

type TickSide 

type TickSide string

TickSide is the aggressor side of a trade, as Webull reports it. The API documents the letters B, S, G, L and N without defining them; B and S are buyer- and seller-initiated and N is neutral. Option ticks also carry an undocumented "NS". 

const (
	TickBuy     TickSide = "B"
	TickSell    TickSide = "S"
	TickNeutral TickSide = "N"
)

Tick sides.

type Ticks 

type Ticks struct {
	Symbol       string `json:"symbol"`
	InstrumentID string `json:"instrument_id"`
	Ticks        []Tick `json:"result"`
}

Ticks is a stock's recent trades, newest first.

type TicksRequest 

type TicksRequest struct {
	Symbol   string
	Category Category
	// Count is between 1 and 1000; zero lets Webull apply its default of 30.
	Count int
	// Sessions restricts results to the given sessions. Empty means all.
	Sessions []TradingSession
}

TicksRequest selects a stock's recent trades.

type Time 

type Time = wire.Time

Time is a point in time transmitted in Webull's ISO 8601 form, such as "2026-08-27T04:00:00.000+0000". It accepts every date form the API uses; the zero value means the field was absent. It is an alias of the shared wire type also used by the events package.

type Timespan 

type Timespan string

Timespan is a bar interval. 

const (
	Minute    Timespan = "M1"
	Minute5   Timespan = "M5"
	Minute15  Timespan = "M15"
	Minute30  Timespan = "M30"
	Minute60  Timespan = "M60"
	Minute120 Timespan = "M120"
	Minute240 Timespan = "M240"
	Daily     Timespan = "D"
	Weekly    Timespan = "W"
	Monthly   Timespan = "M"
	Yearly    Timespan = "Y"
	Second5   Timespan = "S5"  // footprints only
	Second15  Timespan = "S15" // footprints only
)

Bar intervals.

type TopActiveRequest 

type TopActiveRequest struct {
	// Category defaults to USStock.
	Category Category
	// Metric defaults to ByVolume on the server.
	Metric ActivityMetric
	// SortBy defaults to SortVolume on the server.
	SortBy    ScreenerSort
	Direction SortDirection
}

TopActiveRequest selects an activity ranking.

type TradingSession 

type TradingSession string

TradingSession selects a part of the trading day. 

const (
	PreMarket  TradingSession = "PRE"
	Regular    TradingSession = "RTH"
	AfterHours TradingSession = "ATH"
	Overnight  TradingSession = "OVN"
)

Trading sessions.

type Watchlist 

type Watchlist struct {
	ID   string `json:"watchlist_id"`
	Name string `json:"name"`
	// Sort orders watchlists for display.
	Sort       int  `json:"sort"`
	CreateTime Time `json:"create_time"`
	UpdateTime Time `json:"update_time"`
}

Watchlist is one of the account's watchlists.

type WatchlistEntry 

type WatchlistEntry struct {
	Symbol string `json:"symbol"`
	// Category defaults to USStock.
	Category Category `json:"category"`
	// Sort orders the instrument within the watchlist; zero omits it.
	Sort int `json:"sort,omitzero"`
}

WatchlistEntry identifies an instrument in a watchlist mutation.

type WatchlistInstrument 

type WatchlistInstrument struct {
	InstrumentID string `json:"instrument_id"`
	Symbol       string `json:"symbol"`
	Name         string `json:"name"`
	ExchangeCode string `json:"exchange_code"`
	Sort         int    `json:"sort"`
	AddedTime    Time   `json:"added_time"`
}

WatchlistInstrument is one instrument in a watchlist.

type Week52Rank 

type Week52Rank string

Week52Rank selects which 52-week extreme the screener reports. 

const (
	NewHigh  Week52Rank = "NEW_HIGH"
	NearHigh Week52Rank = "NEAR_HIGH"
	NewLow   Week52Rank = "NEW_LOW"
	NearLow  Week52Rank = "NEAR_LOW"
)

52-week rank types.

type Week52Request 

type Week52Request struct {
	// Category defaults to USStock.
	Category Category
	// Rank selects the extreme reported; the server default is NewHigh.
	Rank Week52Rank
	// SortBy defaults to SortChangeRatio52W on the server.
	SortBy ScreenerSort
	// Direction defaults to Ascending on the server.
	Direction SortDirection
}

Week52Request selects a 52-week high-low ranking.

type Week52Stock 

type Week52Stock struct {
	InstrumentID string      `json:"instrument_id"`
	Category     Category    `json:"category"`
	Symbol       string      `json:"symbol"`
	Name         string      `json:"name"`
	ExchangeCode string      `json:"exchange_code"`
	Currency     string      `json:"currency"`
	Close        NullDecimal `json:"close"`
	Change       NullDecimal `json:"change"`
	ChangeRatio  NullDecimal `json:"change_ratio"`
	Price        NullDecimal `json:"price"`
	Volume       NullDecimal `json:"volume"`
	MarketValue  NullDecimal `json:"market_value"`
	TurnoverRate NullDecimal `json:"turnover_rate"`
	Amplitude    NullDecimal `json:"amplitude"`
	High         NullDecimal `json:"high"`
	Low          NullDecimal `json:"low"`
	Turnover     NullDecimal `json:"turnover"`
	// Week1Price and Week52Price are the extreme this week and over 52
	// weeks; ChangeRatio52W is the change since the 52-week extreme.
	Week1Price    NullDecimal `json:"price_1w"`
	Week52Price   NullDecimal `json:"price_52w"`
	ChangeRatio52 NullDecimal `json:"change_ratio_52w"`
	PETTM         NullDecimal `json:"pe_ttm"`
}

Week52Stock is one row of the 52-week high-low screener.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.