Skip to content

webullapi4go

webullapi4go is an idiomatic Go SDK for the Webull OpenAPI. It wraps Webull's HTTP and MQTT services in typed Go, starting with the Hong Kong region.

The current release (v1.1.0) covers authentication, a core signed REST client, Market Data HTTP and MQTT streaming, the Trading HTTP API, Trading events over gRPC, fundamentals and fund data, crypto data, Display Solution, event contracts, options and futures, Broker API HK, Broker FD US, and the Connect API. Every endpoint documented by Webull is implemented, with paths taken from the official OpenAPI definition — see the reconciliation report. The module is licensed under Apache-2.0.

Feature matrix

Area Status
Authentication Supported
Market Data (HTTP) Supported
Market Data Fundamentals Supported — capital flows, industry comparisons, earnings/dividend calendars, SEC filings, financial statements
Market Data (MQTT streaming) Supported
Trading (HTTP) Supported — including multi-leg options and futures order validation
Trading events (gRPC) Supported — order, position, and option streams
Event contracts Supported
Crypto market data Supported — US-only; HK sandbox returns 404
Fund data Supported — info, NAV, dividends, plus performance, holdings, rating, splits, files, allocation
Broker API HK Supported — HK sandbox returns 401 ROUTE_NOT_PERMITTED (app scope missing)
Broker FD US Supported — US-only; HK sandbox returns 404
Display Solution Supported, entitlement-gated — HK sandbox returns 403
Connect API (OAuth) Supported

What's new in v1.1

  • 209 endpoints — full parity with the official Webull OpenAPI (was ~140 in v1.0)
  • 6 new packages — connect, display, broker, brokerfd, brokerfd/events, plus new protobuf types
  • Zero TODO markers — all provisional scaffolding removed
  • Sandbox-tested — 20/20 integration tests pass against the HK sandbox

Architecture

┌──────────────────────────────────────────────────────────────────┐
│                       Your Application                           │
├──────────┬──────────┬──────────┬──────────┬──────────────────────┤
│  client  │   data   │  trade   │  stream  │       events         │
│  (core)  │ (market) │ (orders) │  (MQTT)  │       (gRPC)         │
├──────────┴──────────┴──────────┴──────────┴──────────────────────┤
│                 internal/auth · errs · region                    │
└──────────────────────────────────────────────────────────────────┘
  Display: data.DisplayService()   │  Broker: broker/, brokerfd/
  Connect: connect/ (OAuth)        │  Types:  pkg/types/

Install

go get github.com/shing1211/webullapi4go

Requires Go 1.26 or newer.

Quickstart

package main

import (
    "context"
    "log"

    "github.com/shing1211/webullapi4go/client"
    "github.com/shing1211/webullapi4go/data"
)

func main() {
    cl, err := client.New(client.WithEnv())
    if err != nil {
        log.Fatal(err)
    }
    defer func() { _ = cl.Close() }()

    ctx := context.Background()
    if _, err := cl.EnsureToken(ctx); err != nil {
        log.Fatal(err)
    }

    market := data.New(cl)
    snaps, err := market.GetSnapshot(ctx, data.SnapshotQuery{
        Symbols:  []string{"AAPL"},
        Category: data.StockCategoryUS,
    })
    if err != nil {
        log.Fatal(err)
    }
    for _, s := range snaps {
        log.Printf("%s %s", s.Symbol, s.Price)
    }
}

Set the credentials in the environment first (see Getting Started):

export WEBULL_APP_KEY="your-sandbox-app-key"
export WEBULL_APP_SECRET="your-sandbox-app-secret"
export WEBULL_ENVIRONMENT="sandbox"

Documentation

Disclaimer

This SDK is an independent, unofficial wrapper and is not affiliated with or endorsed by Webull. It is provided for reference and educational use only and is not investment advice.