Skip to content

Trading

Jump to bottom
Igor Sazonov edited this page Aug 9, 2026 · 1 revision

The Trade service covers the Phase 1 order and position endpoints for Bitget UTA. These methods are private, signed REST calls and can create, change, or cancel real orders when production credentials are used. Test integrations with Demo credentials and WithDemoTrading() before enabling any live execution path. 1 2

Scope notice. Batch orders, plan/trigger orders, and other unlisted UTA trade endpoints are not part of the current SDK implementation. 3

Supported methods

Method Signature Returns HTTP endpoint
PlaceOrder PlaceOrder(ctx, req) *models.OrderRef POST /api/v3/trade/place-order
ModifyOrder ModifyOrder(ctx, req) *models.OrderRef POST /api/v3/trade/modify-order
CancelOrder CancelOrder(ctx, req) *models.OrderRef POST /api/v3/trade/cancel-order
GetOpenOrders GetOpenOrders(ctx, opts) *models.OrderList GET /api/v3/trade/unfilled-orders
GetOrderHistory GetOrderHistory(ctx, opts) *models.OrderList GET /api/v3/trade/history-orders
GetPositions GetPositions(ctx, category, symbol, posSide) *models.PositionList GET /api/v3/position/current-position

The service returns a typed OrderRef after create, amend, or cancel. It exposes both the exchange-assigned OrderID and the client-supplied ClientOid when provided by Bitget. 1 4

Place an order

models.PlaceOrderRequest contains the request fields implemented by the SDK. At a minimum, choose a product category, symbol, quantity, side, and order type. A limit order normally needs Price; TimeInForce, position settings, client order ID, and TP/SL fields are optional JSON fields. Exact exchange-side constraints depend on the relevant Bitget endpoint and instrument specification. 4 5

order, err := client.Trade.PlaceOrder(ctx, models.PlaceOrderRequest{
    Category:    models.CategorySpot,
    Symbol:      "BTCUSDT",
    Qty:         "0.001",
    Price:       "10000",
    Side:        models.SideBuy,
    OrderType:   models.OrderTypeLimit,
    TimeInForce: models.TimeInForceGTC,
    ClientOid:   "strategy-a-20260809-001",
})
if err != nil {
    return err
}

fmt.Printf("order ID=%s client OID=%s\n", order.OrderID, order.ClientOid)

The repository example deliberately places a far-from-market Demo limit order and requires both BITGET_DEMO=1 and BITGET_ENABLE_TRADING=1 before it submits. Reuse the two-gate pattern or an equivalent explicit control in automated applications. 6

Place-order fields

Field Type Purpose
Category, Symbol, Qty string aliases / string Product, instrument, and requested quantity.
Price string Limit price when appropriate.
Side models.Side models.SideBuy or models.SideSell.
OrderType models.OrderType models.OrderTypeLimit or models.OrderTypeMarket.
TimeInForce models.TimeInForce Optional execution instruction such as GTC, IOC, or FOK.
PosSide, MarginMode, ReduceOnly String aliases / string Futures and margin controls where applicable.
ClientOid string Application-defined client order identifier.
TP/SL fields string / models.OrderType Optional take-profit and stop-loss instruction fields.

The Go struct uses omitempty for optional fields. Omitting a field is not equivalent to submitting an empty string in every exchange scenario; build the request to match Bitget's current endpoint requirements. 4 5

Amend or cancel an order

ModifyOrderRequest and CancelOrderRequest can address an order by OrderID or ClientOid. The SDK model documentation states that OrderID takes precedence if both are set. 4

updated, err := client.Trade.ModifyOrder(ctx, models.ModifyOrderRequest{
    OrderID: "123456789",
    Qty:     "0.002",
    Price:   "9999",
})
if err != nil {
    return err
}
fmt.Println("amended order:", updated.OrderID)

cancelled, err := client.Trade.CancelOrder(ctx, models.CancelOrderRequest{
    OrderID:  updated.OrderID,
    Category: models.CategorySpot,
})
if err != nil {
    return err
}
fmt.Println("cancelled order:", cancelled.OrderID)

List open orders and historical orders

Both list methods take options structs with Category, Symbol, StartTime, EndTime, Limit, and Cursor string fields. Empty fields are omitted from the request query. GetOrderHistoryOptions.Category is documented by the SDK as required by the endpoint. The implemented history method documents a maximum 30-day time window within a 90-day lookback. 1

open, err := client.Trade.GetOpenOrders(ctx, trade.GetOpenOrdersOptions{
    Category: models.CategorySpot,
    Symbol:   "BTCUSDT",
    Limit:    "50",
})
if err != nil {
    return err
}

for _, order := range open.List {
    fmt.Printf("%s %s %s status=%s\n", order.OrderID, order.Side, order.Qty, order.OrderStatus)
}

history, err := client.Trade.GetOrderHistory(ctx, trade.GetOrderHistoryOptions{
    Category:  models.CategorySpot,
    Symbol:    "BTCUSDT",
    StartTime: "1760000000000",
    EndTime:   "1760086400000",
    Limit:     "50",
})
if err != nil {
    return err
}
fmt.Println("next cursor:", history.Cursor)

Import the options package in this example:

import "github.com/tigusigalpa/bitget-go/rest/trade"

models.OrderList contains List []models.Order and a pagination Cursor. An Order records IDs, price, quantity, execution totals, status, fees, order controls, and created/updated timestamps. All numeric financial fields remain strings. 4

Retrieve positions

Use GetPositions for currently open futures positions. symbol and posSide are optional filters; pass "" to omit either. 1

positions, err := client.Trade.GetPositions(
    ctx,
    models.CategoryUSDTFutures,
    "BTCUSDT",
    models.PosSideLong,
)
if err != nil {
    return err
}

for _, position := range positions.List {
    fmt.Printf(
        "%s %s total=%s entry=%s mark=%s PnL=%s\n",
        position.Symbol,
        position.PosSide,
        position.Total,
        position.AvgPrice,
        position.MarkPrice,
        position.UnrealisedPnl,
    )
}

models.Position includes product, margin, quantity, leverage, PnL, liquidation, mark-price, funding, and timestamp fields. Consumers should preserve the strings or convert them with exact decimal arithmetic rather than float64. 4

Order safety checklist

Before calling a mutating method Why it matters
Fetch and validate instrument constraints. Order size, precision, and allowed types are symbol-specific.
Use an explicit context deadline. An order request that outlives its business decision may be unsafe.
Submit a unique ClientOid where your workflow benefits from idempotent reconciliation. It gives the application a stable correlation value.
Start with Demo credentials and WithDemoTrading(). It isolates integration validation from production funds.
Handle errors.Is and errors.As. This distinguishes known conditions from detailed exchange responses.
Reconcile outcomes through queries and/or private streams. A timeout at the caller does not itself establish the exchange-side order outcome.

References

Clone this wiki locally