@spec account_balance(pid(), String.t() | nil) :: {:ok, map()} | {:error, term()}

Returns account balance across all currencies. Optionally filter by currency (e.g. "HKD", "USD").

@spec cancel_order(pid(), String.t()) :: {:ok, map()} | {:error, term()}

Cancels an order by order_id.

Returns {:ok, %{}} (the API responds with a 200 + empty body on success). If the order is already in a terminal state (:filled, :cancelled), the API returns an error that surfaces as {:error, reason} — check it before reporting success to the caller.

Endpoint: DELETE /v1/trade/order

@spec cash_flow(
  pid(),
  keyword()
) :: {:ok, map()} | {:error, term()}

Returns cash flow history.

Options

• :start_at — Start time as Unix timestamp (seconds).
• :end_at — End time as Unix timestamp (seconds).
• :business_type — :cash, :stock, or :fund.
• :symbol — Stock symbol filter.
• :page — Page number (default 1).
• :size — Page size (default 50).

Returns a specification to start this module under a supervisor.

See Supervisor.

@spec estimate_max_purchase_quantity(
  pid(),
  keyword()
) :: {:ok, map()} | {:error, term()}

Estimates the maximum purchase quantity for a symbol.

Options

• :symbol — Stock symbol (required).
• :order_type — Order type (required).
• :side — :buy or :sell (required).
• :price — Price as a string (optional).
• :currency — Currency (optional).
• :fractional_shares — Boolean (optional, default false).

@spec fund_positions(pid(), [String.t()] | nil) :: {:ok, map()} | {:error, term()}

Returns fund positions. Optionally filter by symbols (list of strings).

@spec history_executions(
  pid(),
  keyword()
) :: {:ok, map()} | {:error, term()}

Returns historical executions. Requires:

• :start_at — Start time as a Unix timestamp (seconds).
• :end_at — End time as a Unix timestamp (seconds).

@spec history_orders(
  pid(),
  keyword()
) :: {:ok, map()} | {:error, term()}

Returns historical orders. Requires:

• :start_at — Start time as a Unix timestamp (seconds).
• :end_at — End time as a Unix timestamp (seconds).

@spec margin_ratio(pid(), String.t()) :: {:ok, map()} | {:error, term()}

Returns the initial/maintain margin ratios for a symbol.

Endpoint: GET /v1/risk/margin-ratio?symbol=<s>. Useful for margin checks before submitting levered orders. The response has im_factor (initial margin factor), mm_factor (maintain margin factor), fm_factor, mcm_factor, short_im_factor, and short_fm_factor — all decimal strings.

@spec on_order_changed(pid(), (map() -> any())) :: :ok

Alias for set_on_order_changed/2. Mirrors the upstream OnOrderChanged method name.

@spec order_detail(pid(), String.t()) :: {:ok, map()} | {:error, term()}

Returns the full state for a single order.

Endpoint: GET /v1/trade/order?order_id=<id>. Includes current status, filled quantity, average fill price, fees, and timestamps. Use today_orders/2 (or history_orders/2) to find the order_id if you don't have it.

@spec put_callback(pid(), String.t(), (map() -> any())) :: :ok

Sets a callback for a specific push topic.

The callback receives the decoded JSON event map for the given topic (e.g., @order_changed_topic).

See set_on_order_changed/2 for a convenience wrapper.

@spec remove_callback(pid(), String.t()) :: :ok

Removes the callback for a specific push topic.

@spec replace_order(
  pid(),
  keyword()
) :: {:ok, map()} | {:error, term()}

Replaces (amends) an existing order.

Options

• :order_id — The order to replace (required).
• :quantity — New quantity as a string (required).
• :price — New price as a string (required).

@spec session(pid()) :: {:ok, String.t() | nil, integer() | nil} | {:error, term()}

Returns the current WS session info.

Returns {:ok, session_id, heartbeat_interval_ms} once the underlying Longbridge.WSConnection has finished authenticating, or {:ok, nil, nil} before auth completes.

session_id is the opaque string assigned by the Longbridge backend (e.g. "15766270:21526413:...").

@spec set_default_push_callback(pid(), (map() -> any())) :: :ok

Sets a fallback callback invoked when push data arrives for a topic with no registered callback.

@spec set_on_order_changed(pid(), (map() -> any())) :: :ok

Sets a callback for order-changed push events.

The callback receives a map with fields like order_id, status, filled_qty, executed_price, etc.

Set this before calling subscribe/2 so you don't miss events.

@spec start_link(
  Longbridge.Config.t(),
  keyword()
) :: GenServer.on_start()

Starts a TradeContext linked to the calling process.

The context owns both:

• a Longbridge.WSConnection to config.trade_ws_url for push subscriptions (order-changed events, etc.). Auth uses the OTP from Longbridge.Config.with_socket_token/1.
• a per-instance HTTP config for signed REST requests (orders, account, executions, positions, cash flow). The original config.token is kept on state.http_config so HTTP requests sign with the long-lived access token, while WS auth uses the OTP from ws_config.

Options

• :name — registered process name, passed through to GenServer.start_link/3.
• :token_refresher — nil (default) or a 1-arity function that refreshes the HTTP access token. The default uses Longbridge.Config.refresh_access_token/1, which only works for legacy app-key auth. OAuth users must inject a custom refresher that performs the refresh_token grant.
• :skip_connection — when true, skip WS startup (HTTP-only context). Used by tests; not part of the stable API.
• Any other GenServer option (:timeout, :spawn_opt, ...).

Example

{:ok, ctx} =
  Longbridge.TradeContext.start_link(config,
    token_refresher: fn cfg ->
      with {:ok, %OAuth.Token{access_token: t, expires_at: exp}} <-
             MyApp.OAuth.refresh(cfg.client_id) do
        {:ok, %{cfg | token: t, expired_at: exp}}
      end
    end
  )

@spec stock_positions(pid(), [String.t()] | nil) :: {:ok, map()} | {:error, term()}

Returns stock positions. Optionally filter by symbols (list of strings).

@spec submit_order(
  pid(),
  keyword()
) :: {:ok, map()} | {:error, term()}

Submits a new order.

See the Longbridge Submit Order docs.

Options

• :symbol — Stock symbol in ticker.region format (required).
• :side — :buy or :sell (required).
• :order_type — Order type (required). See order_type/0.
• :submitted_quantity — Quantity as a string (required).
• :time_in_force — :day, :gtc, or :gtd (required).
• :submitted_price — Price as a string. Required for LO/ELO/ALO/ODD/LIT.
• :trigger_price — Trigger price. Required for LIT/MIT.
• :limit_offset — Limit offset. Required for TSLPAMT/TSLPPCT when limit_depth_level is 0.
• :trailing_amount — Trailing amount for TSLPAMT.
• :trailing_percent — Trailing percent for TSLPPCT.
• :expire_date — Expiry date as "YYYY-MM-DD". Required for GTD.
• :outside_rth — Outside RTH mode. For US stocks only.
• :remark — Remark (max 255 chars).
• :limit_depth_level — Bid/ask depth level (-5 to 5).
• :monitor_price — Monitoring price for TSLPAMT/TSLPPCT.
• :trigger_count — Trigger count (0-3).

@spec subscribe(pid(), [atom()]) :: :ok | {:error, term()}

Subscribes to trade push data. Accepts a list of topics:

• :private — Order status updates.

Set a callback with set_on_order_changed/2 first to receive structured push events. Raw events arrive at the caller's mailbox as {:longbridge_push, {:push, cmd_code, body}} messages.

@spec today_executions(
  pid(),
  keyword()
) :: {:ok, map()} | {:error, term()}

Returns today's executions. Accepts optional filters:

• :symbol — Stock symbol.
• :order_id — A specific order ID.

@spec today_orders(
  pid(),
  keyword()
) :: {:ok, map()} | {:error, term()}

Returns today's orders. Accepts optional filters:

• :symbol — Stock symbol.
• :status — List of order statuses (atoms).
• :side — :buy or :sell.
• :market — :us, :hk, :cn, :sg.
• :order_id — A specific order ID.

@spec unsubscribe(pid(), [atom()]) :: :ok | {:error, term()}

Unsubscribes from trade push topics.

topics is a list of atoms; currently :private is the only supported value (it controls order-changed events). Passing an empty list is a no-op. Mirrors Unsubscribe (cmd_code 17).