Trading

The Go SDK exposes all trading endpoints through TradeClient. Every method returns a strongly-typed struct from the model package. Place / modify / preview use the request struct model.OrderRequest (snake_case json tags that match the server); starting with v0.3.0, all read methods accept a matching Request struct (every field optional; leaving Account empty auto-fills the default account).

A complete runnable example:

package main

import (
	"fmt"
	"log"

	"github.com/tigerfintech/openapi-go-sdk/client"
	"github.com/tigerfintech/openapi-go-sdk/config"
	"github.com/tigerfintech/openapi-go-sdk/model"
	"github.com/tigerfintech/openapi-go-sdk/trade"
)

func main() {
	cfg, err := config.NewClientConfig()
	if err != nil {
		log.Fatal(err)
	}

	tc := trade.NewTradeClient(client.NewHttpClient(cfg), cfg.Account)

	// Positions
	positions, err := tc.Positions(model.PositionsRequest{})
	if err != nil {
		log.Fatal(err)
	}
	for _, p := range positions {
		fmt.Printf("%s qty=%.2f avgCost=%.2f marketValue=%.2f\n",
			p.Symbol, p.PositionQty, p.AverageCost, p.MarketValue)
	}

	// Build and preview a limit order
	order := model.LimitOrder(cfg.Account, "AAPL", "STK", "BUY", 10, 150.0)
	preview, err := tc.PreviewOrder(order)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("isPass=%v commission=%.2f initMargin=%.2f\n",
		preview.IsPass, preview.Commission, preview.InitMargin)

	// Place the order
	placed, err := tc.PlaceOrder(order)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("order id=%d orderId=%d\n", placed.ID, placed.OrderID)
}

Contract queries

Contract — single contract

tc.Contract(symbol, secType string) ([]model.Contract, error)

Description

Fetch details of a single contract.

Parameters

Returns

[]model.Contract (common fields below)

Example

cs, err := tc.Contract("AAPL", "STK")
if err != nil {
    log.Fatal(err)
}
if len(cs) > 0 {
    fmt.Printf("%s contractId=%d exchange=%s\n", cs[0].Symbol, cs[0].ContractId, cs[0].PrimaryExchange)
}

Contracts — batch contracts

tc.Contracts(symbols []string, secType string) ([]model.Contract, error)

Description

Batch fetch multiple contracts.

Parameters

Returns

[]model.Contract (same as Contract)

Example

cs, err := tc.Contracts([]string{"AAPL", "TSLA", "MSFT"}, "STK")

QuoteContract — derivative contracts

tc.QuoteContract(symbol, secType, expiry string) ([]model.Contract, error)

Description

Fetch derivative contracts (options / warrants / callable bull bear). Supports OPT / WAR / IOPT only.

Parameters

Returns

[]model.Contract

Example

cs, err := tc.QuoteContract("AAPL", "OPT", "20260619")
if err != nil {
    log.Fatal(err)
}
fmt.Printf("options=%d\n", len(cs))

Order operations

OrderRequest — order request struct

model.OrderRequest is the request object used by place / preview / modify. Fields have snake_case json tags aligned with the server:

Convenience constructors

order := model.MarketOrder(account, symbol, secType, action, qty)
order := model.LimitOrder(account, symbol, secType, action, qty, price)
order := model.StopOrder(account, symbol, secType, action, qty, auxPrice)
order := model.StopLimitOrder(account, symbol, secType, action, qty, limit, aux)
order := model.TrailOrder(account, symbol, secType, action, qty, trailPct)

PlaceOrder — place an order

tc.PlaceOrder(order model.OrderRequest) (*model.PlaceOrderResult, error)

Description

Submit an order to the exchange.

Returns

*model.PlaceOrderResult

Example

order := model.LimitOrder(cfg.Account, "AAPL", "STK", "BUY", 10, 150.0)
order.Market = "US"
order.Currency = "USD"

placed, err := tc.PlaceOrder(order)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("id=%d orderId=%d\n", placed.ID, placed.OrderID)

PreviewOrder — preview an order

tc.PreviewOrder(order model.OrderRequest) (*model.PreviewResult, error)

Description

Estimate commission and margin impact without actually submitting.

Returns

*model.PreviewResult

Example

preview, err := tc.PreviewOrder(order)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("isPass=%v commission=%.2f initMargin=%.2f\n",
    preview.IsPass, preview.Commission, preview.InitMargin)

ModifyOrder — modify an order

tc.ModifyOrder(id int64, order model.OrderRequest) (*model.OrderIDResult, error)

Description

Modify an open order.

Parameters

Returns

*model.OrderIDResult (contains ID)

Example

modifyReq := order
modifyReq.LimitPrice = 148.0
mod, err := tc.ModifyOrder(placed.ID, modifyReq)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("modified id=%d\n", mod.ID)

CancelOrder — cancel an order

tc.CancelOrder(id int64) (*model.OrderIDResult, error)

Description

Cancel an open order.

Parameters

Returns

*model.OrderIDResult

Example

canc, err := tc.CancelOrder(placed.ID)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("cancelled id=%d\n", canc.ID)

Order queries

Order status enum (v0.3.0, aligned with the Java SDK)

The model package provides an OrderStatus type and 8 constants; call OrderStatus.Code() to get the server-side numeric code. Order.Status is a string — when the server returns an integer it is automatically mapped to the string below during unmarshalling.

Constant	String	Code
OrderStatusInvalid	"Invalid"	-2
OrderStatusInitial	"Initial"	-1
OrderStatusPendingCancel	"PendingCancel"	3
OrderStatusCancelled	"Cancelled"	4
OrderStatusSubmitted	"Submitted"	5
OrderStatusFilled	"Filled"	6
OrderStatusInactive	"Inactive"	7
OrderStatusPendingSubmit	"PendingSubmit"	8

Use these string values in OrdersRequest.States (e.g. []string{"Filled", "Submitted"}).

OrdersRequest — orders query request struct

model.OrdersRequest is shared by Orders / ActiveOrders / InactiveOrders / FilledOrders. Every field is optional (leave Account empty to auto-fill the default account).

Orders — all orders

tc.Orders(req model.OrdersRequest) ([]model.Order, error)

Description

Fetch all historical orders for the current account. Since v0.3.0 the method takes an OrdersRequest, so you can filter by time range, status, contract, etc.

Parameters

See OrdersRequest above.

Returns

[]model.Order (common fields below)

Example

// Minimal call: fetch all orders
orders, err := tc.Orders(model.OrdersRequest{})
if err != nil {
    log.Fatal(err)
}

// Filtered call: latest 100 filled US stock orders
orders, err = tc.Orders(model.OrdersRequest{
    Market:  "US",
    SecType: "STK",
    States:  []string{"Filled"},
    Limit:   100,
    SortBy:  "LATEST_CREATED",
})
for _, o := range orders {
    fmt.Printf("%d %s %s %s qty=%d filled=%d status=%s\n",
        o.ID, o.Symbol, o.Action, o.OrderType, o.TotalQuantity, o.FilledQuantity, o.Status)
}

GetOrder — fetch a single order by ID

tc.GetOrder(req model.GetOrderRequest) (*model.Order, error)

Description

Fetch a single order by ID. At least one of Id (global order ID) or OrderId (account-level order number) is required.

Parameters

Returns

*model.Order (same fields as items from Orders)

Example

o, err := tc.GetOrder(model.GetOrderRequest{Id: placed.ID})
if err != nil {
    log.Fatal(err)
}
fmt.Printf("%d %s status=%s filled=%d/%d\n",
    o.ID, o.Symbol, o.Status, o.FilledQuantity, o.TotalQuantity)

ActiveOrders — pending orders

tc.ActiveOrders(req model.OrdersRequest) ([]model.Order, error)

Description

Fetch orders currently open (not fully filled). Since v0.3.0 the method accepts an OrdersRequest and supports ParentId for listing children of a given parent order.

Parameters

See OrdersRequest.

Returns

[]model.Order

Example

// Minimal call
activeOrders, err := tc.ActiveOrders(model.OrdersRequest{})

// Children of a specific parent order
activeOrders, err = tc.ActiveOrders(model.OrdersRequest{ParentId: 12345678})

InactiveOrders — cancelled/expired orders

tc.InactiveOrders(req model.OrdersRequest) ([]model.Order, error)

Description

Fetch cancelled or expired orders. Since v0.3.0 the method accepts an OrdersRequest for filtering.

Parameters

See OrdersRequest.

Returns

[]model.Order

Example

// Minimal call
inactive, err := tc.InactiveOrders(model.OrdersRequest{})

// Cancelled only
inactive, err = tc.InactiveOrders(model.OrdersRequest{
    States: []string{"Cancelled"},
    Limit:  50,
})

FilledOrders — filled orders

tc.FilledOrders(req model.OrdersRequest) ([]model.Order, error)

Description

Fetch filled orders. Since v0.3.0 the two positional args (startDateMs, endDateMs int64) are replaced by an OrdersRequest; pass the time window via StartDate / EndDate.

Parameters

See OrdersRequest. StartDate / EndDate are ms timestamps.

Returns

[]model.Order

Example

import "time"

// Minimal call: no time window (server default applies)
filled, err := tc.FilledOrders(model.OrdersRequest{})

// Filtered: last 30 days
now := time.Now().UnixMilli()
filled, err = tc.FilledOrders(model.OrdersRequest{
    StartDate: now - 30*24*3600*1000,
    EndDate:   now,
    Limit:     200,
})

OrderTransactions — order transactions

tc.OrderTransactions(req model.OrderTransactionsRequest) ([]model.Transaction, error)

Description

Fetch fill-by-fill transaction records for an order. Since v0.3.0 the method accepts an OrderTransactionsRequest; you can look up transactions for a specific order via OrderId, or query a batch by time window / contract.

Parameters

Returns

[]model.Transaction

Example

// Minimal call: transactions for a specific order
txs, err := tc.OrderTransactions(model.OrderTransactionsRequest{
    OrderId: placed.ID,
    Symbol:  "AAPL",
    SecType: "STK",
})

// Filtered: all transactions on a contract within a time window
txs, err = tc.OrderTransactions(model.OrderTransactionsRequest{
    Symbol:    "AAPL",
    SecType:   "STK",
    StartDate: now - 7*24*3600*1000,
    EndDate:   now,
    Limit:     100,
})
for _, tx := range txs {
    fmt.Printf("%s %s filledPrice=%.2f qty=%d\n", tx.TransactedAt, tx.Action, tx.FilledPrice, tx.FilledQuantity)
}

Positions and assets

Positions — positions

tc.Positions(req model.PositionsRequest) ([]model.Position, error)

Description

Fetch all positions for the current account. Since v0.3.0 the method accepts a PositionsRequest and supports filtering by Symbol / SecType / Currency / Market / SubAccounts, etc.

Parameters

Returns

[]model.Position

Example

// Minimal call: all positions
ps, err := tc.Positions(model.PositionsRequest{})

// Filtered: US stocks only
ps, err = tc.Positions(model.PositionsRequest{
    Market:  "US",
    SecType: "STK",
})
for _, p := range ps {
    fmt.Printf("%s qty=%.0f avgCost=%.2f latest=%.2f pnl=%.2f\n",
        p.Symbol, p.PositionQty, p.AverageCost, p.LatestPrice, p.UnrealizedPnl)
}

Assets — account assets

tc.Assets(req model.AssetsRequest) ([]model.Asset, error)

Description

Fetch an overview of account assets (with per-segment breakdown). Since v0.3.0 the method accepts an AssetsRequest.

Parameters

Returns

[]model.Asset

Each Asset contains account-level aggregates (BuyingPower / CashValue / NetLiquidation / RealizedPnL / UnrealizedPnL / Currency / Capability) plus Segments []AssetSegment.

Each AssetSegment has Category (e.g. "S" for securities, "C" for commodities) / Title / NetLiquidation / CashValue / AvailableFunds / EquityWithLoan / ExcessLiquidity / InitMarginReq / MaintMarginReq / GrossPositionValue / Leverage.

Example

// Minimal call
assets, err := tc.Assets(model.AssetsRequest{})

// Filtered: include segment breakdown
assets, err = tc.Assets(model.AssetsRequest{
    Segment:     true,
    MarketValue: true,
})
for _, a := range assets {
    fmt.Printf("account=%s buyingPower=%.2f netLiq=%.2f segments=%d\n",
        a.Account, a.BuyingPower, a.NetLiquidation, len(a.Segments))
    for _, s := range a.Segments {
        fmt.Printf("  [%s] %s netLiq=%.2f available=%.2f\n",
            s.Category, s.Title, s.NetLiquidation, s.AvailableFunds)
    }
}

PrimeAssets — prime account assets

tc.PrimeAssets(req model.AssetsRequest) (*model.PrimeAsset, error)

Description

Fetch detailed assets for a prime account. Since v0.3.0 the method accepts an AssetsRequest (shared with Assets).

Parameters

See the AssetsRequest in Assets.

Returns

*model.PrimeAsset

Each PrimeAssetSegment has the full set: Capability / Category / Currency / CashBalance / CashAvailableForTrade / GrossPositionValue / EquityWithLoan / NetLiquidation / InitMargin / MaintainMargin / OvernightMargin / UnrealizedPL / RealizedPL / TotalTodayPL / BuyingPower / LockedFunds / Leverage, plus CurrencyAssets []CurrencyAsset (Currency / CashBalance / CashAvailableForTrade / ForexRate).

Example

// Minimal call
pa, err := tc.PrimeAssets(model.AssetsRequest{})

// Filtered: specify base currency
pa, err = tc.PrimeAssets(model.AssetsRequest{BaseCurrency: "USD"})
if err != nil {
    log.Fatal(err)
}
fmt.Printf("account=%s segments=%d\n", pa.AccountID, len(pa.Segments))
for _, s := range pa.Segments {
    fmt.Printf("  [%s] netLiq=%.2f buyingPower=%.2f\n",
        s.Category, s.NetLiquidation, s.BuyingPower)
    for _, ca := range s.CurrencyAssets {
        fmt.Printf("    %s cash=%.2f fx=%.4f\n", ca.Currency, ca.CashBalance, ca.ForexRate)
    }
}

Account management (new in v0.3.0)

ManagedAccounts — institutional sub-accounts

tc.ManagedAccounts(req model.ManagedAccountsRequest) ([]model.ManagedAccount, error)

Description

List the institutional sub-accounts that the current master account can manage.

Parameters

Returns

[]model.ManagedAccount

Example

subs, err := tc.ManagedAccounts(model.ManagedAccountsRequest{})
if err != nil {
    log.Fatal(err)
}
for _, s := range subs {
    fmt.Printf("%s type=%s capability=%s status=%s\n",
        s.Account, s.AccountType, s.Capability, s.Status)
}

DerivativeContracts — derivative contracts

tc.DerivativeContracts(req model.DerivativeContractsRequest) ([]model.Contract, error)

Description

Batch fetch derivative contracts (options / warrants / callable bull bear) by symbols + type.

Parameters

Returns

[]model.Contract (see Contract)

Example

cs, err := tc.DerivativeContracts(model.DerivativeContractsRequest{
    Symbols: []string{"AAPL", "TSLA"},
    SecType: "OPT",
    Expiry:  "20260619",
})
fmt.Printf("contracts=%d\n", len(cs))

Asset analytics (new in v0.3.0)

AnalyticsAsset — daily asset analytics

tc.AnalyticsAsset(req model.AnalyticsAssetRequest) ([]model.AnalyticsAsset, error)

Description

Return daily account holdings, cash balance, P&L and net-value index — useful for drawing an account performance curve.

Parameters

Returns

[]model.AnalyticsAsset

Example

rows, err := tc.AnalyticsAsset(model.AnalyticsAssetRequest{
    StartDate: "2025-01-01",
    EndDate:   "2025-12-31",
    Currency:  "USD",
})
for _, r := range rows {
    fmt.Printf("%s holding=%.2f cash=%.2f pnl=%.2f nav=%.4f\n",
        r.Date, r.HoldingValue, r.CashBalance, r.Pnl, r.NetValueIndex)
}

AggregateAssets — aggregated account assets

tc.AggregateAssets(req model.AggregateAssetsRequest) (*model.AggregateAssets, error)

Description

Aggregate prime-account assets under a given base_currency view (with per-currency breakdown).

Parameters

Returns

*model.AggregateAssets

Example

agg, err := tc.AggregateAssets(model.AggregateAssetsRequest{BaseCurrency: "USD"})
if err != nil {
    log.Fatal(err)
}
fmt.Printf("netLiq=%.2f gross=%.2f cash=%.2f currencies=%d\n",
    agg.NetLiquidation, agg.GrossPositionValue, agg.CashBalance, len(agg.CurrencyAssets))

EstimateTradableQuantity — estimate tradable quantity

tc.EstimateTradableQuantity(req model.EstimateTradableQuantityRequest) (*model.EstimateTradableQuantity, error)

Description

Estimate order quantity limits (cash buy, margin buy, short sell, sellable, etc.) from the account's available funds, margin and current price.

Parameters

Returns

*model.EstimateTradableQuantity

Example

est, err := tc.EstimateTradableQuantity(model.EstimateTradableQuantityRequest{
    Symbol:     "AAPL",
    SecType:    "STK",
    Action:     "BUY",
    OrderType:  "LMT",
    LimitPrice: 150.0,
})
if err != nil {
    log.Fatal(err)
}
fmt.Printf("tradable=%.2f cashBuy=%.2f marginBuy=%.2f\n",
    est.TradableQuantity, est.MaxCashBuyQuantity, est.MaxMarginBuyQuantity)

Fund details & transfers (new in v0.3.0)

FundDetails — fund flow details

tc.FundDetails(req model.FundDetailsRequest) ([]model.FundDetails, error)

Description

Fetch account fund flow entries over a time window (deposits / withdrawals / fees / interest / dividends, etc.).

Parameters

Returns

[]model.FundDetails

Example

now := time.Now().UnixMilli()
rows, err := tc.FundDetails(model.FundDetailsRequest{
    StartDate: now - 30*24*3600*1000,
    EndDate:   now,
    Currency:  "USD",
    Limit:     100,
})
for _, r := range rows {
    fmt.Printf("%d %s amount=%.2f balance=%.2f remark=%s\n",
        r.OccurTime, r.FundType, r.Amount, r.Balance, r.Remark)
}

FundingHistory — funding history

tc.FundingHistory(req model.FundingHistoryRequest) ([]model.FundingHistoryItem, error)

Description

Query deposit / withdrawal transfer records for the account.

Parameters

Returns

[]model.FundingHistoryItem

Example

rows, err := tc.FundingHistory(model.FundingHistoryRequest{})
for _, r := range rows {
    fmt.Printf("%s %s amount=%.2f status=%s\n", r.ID, r.Currency, r.Amount, r.Status)
}

PlaceForexOrder — place a forex order

tc.PlaceForexOrder(req model.ForexOrderRequest) (*model.ForexOrderResult, error)

Description

Submit a forex conversion order (currency-to-currency).

Parameters

Returns

*model.ForexOrderResult

Example

res, err := tc.PlaceForexOrder(model.ForexOrderRequest{
    SourceCurrency: "USD",
    SourceAmount:   10000,
    TargetCurrency: "HKD",
})
if err != nil {
    log.Fatal(err)
}
fmt.Printf("id=%s rate=%.4f target=%.2f\n", res.ID, res.Rate, res.TargetAmount)

SegmentFundAvailable — available transfer amount

tc.SegmentFundAvailable(req model.SegmentFundRequest) ([]model.SegmentFund, error)

Description

Query the maximum amount that can be transferred between sub-account segments.

Parameters

Returns

[]model.SegmentFund

Example

avail, err := tc.SegmentFundAvailable(model.SegmentFundRequest{
    FromSegment: "S",
    ToSegment:   "C",
    Currency:    "USD",
})
for _, a := range avail {
    fmt.Printf("%s->%s %s available=%.2f\n", a.FromSegment, a.ToSegment, a.Currency, a.AvailableAmt)
}

SegmentFundHistory — segment fund history

tc.SegmentFundHistory(req model.SegmentFundRequest) ([]model.SegmentFundHistoryItem, error)

Description

Query the history of sub-account fund transfers.

Parameters

Uses SegmentFundRequest (commonly with Limit to cap result size).

Returns

[]model.SegmentFundHistoryItem

Example

history, err := tc.SegmentFundHistory(model.SegmentFundRequest{Limit: 50})
for _, h := range history {
    fmt.Printf("%d %s->%s %s amount=%.2f status=%s\n",
        h.ID, h.FromSegment, h.ToSegment, h.Currency, h.Amount, h.Status)
}

TransferSegmentFund — transfer between segments

tc.TransferSegmentFund(req model.SegmentFundRequest) (*model.SegmentFund, error)

Description

Submit a fund-transfer request between sub-account segments.

Parameters

Returns

*model.SegmentFund (with ID / Status / SubmitTime, etc.)

Example

res, err := tc.TransferSegmentFund(model.SegmentFundRequest{
    FromSegment: "S",
    ToSegment:   "C",
    Currency:    "USD",
    Amount:      1000,
})
fmt.Printf("transferId=%s status=%s\n", res.ID, res.Status)

CancelSegmentFund — cancel a transfer request

tc.CancelSegmentFund(req model.SegmentFundRequest) (*model.SegmentFund, error)

Description

Cancel a pending sub-account fund-transfer request.

Parameters

Returns

*model.SegmentFund

Example

res, err := tc.CancelSegmentFund(model.SegmentFundRequest{ID: "TX123456"})
fmt.Printf("cancelled id=%s status=%s\n", res.ID, res.Status)

Low-level access

For endpoints not yet wrapped by the SDK, call the low-level HttpClient.ExecuteRaw:

package main

import (
	"fmt"
	"log"

	"github.com/tigerfintech/openapi-go-sdk/client"
	"github.com/tigerfintech/openapi-go-sdk/config"
)

func main() {
	cfg, err := config.NewClientConfig()
	if err != nil {
		log.Fatal(err)
	}

	httpClient := client.NewHttpClient(cfg)

	// Pass the API method name and raw JSON parameters
	resp, err := httpClient.ExecuteRaw("market_state", `{"market":"US"}`)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("raw response:", resp)
}