Help us shape the future of Go! Take the 2026 Go Developer Survey

api

package
v0.0.8 Latest Latest
Warning

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

Go to latest
Published: Oct 30, 2026 License: AGPL-3.0 Imports: 19 Imported by: 0

Documentation

Overview

Package api is the CLI's client for the Oku account API. Calls go through connect-go clients generated from the vendored protos (pkg/gen), over an HTTP client that refuses redirects, with a single attempt and no retries.

Index

Constants

View Source
const (
	SessionHeader      = "x-oku-account-session"
	SessionTokenHeader = "x-oku-account-session-token"
)

Variables

This section is empty.

Functions

func NewHTTPClient

func NewHTTPClient(timeout time.Duration) *http.Client

NewHTTPClient returns an HTTP client that never follows redirects, so the session credentials can never be forwarded to another origin, and that has a hard overall timeout as a backstop to the context deadline.

func Redact

func Redact(s string) string

Redact removes credential-like substrings. Addresses and hashes are 0x-prefixed hex and kept only if shorter than 32 chars after the prefix, which errs on the side of redaction.

Types

type AccountSession

type AccountSession struct {
	SessionID string `json:"sessionId"`
	Token     string `json:"token"`
	ExpiresAt string `json:"expiresAt"`
}

AccountSession is the Oku session returned by AuthService.

type ActionParams

type ActionParams struct {
	Order    *OrderActionMetadata    `json:"order,omitempty"`
	Cancel   *CancelActionMetadata   `json:"cancel,omitempty"`
	Leverage *LeverageActionMetadata `json:"leverage,omitempty"`
	Margin   *MarginActionMetadata   `json:"margin,omitempty"`
}

type ActionPayloadResponse

type ActionPayloadResponse struct {
	ActionID   string `json:"actionId"`
	ActionType string `json:"actionType"`
	Status     string `json:"status"`
	ActionJSON string `json:"actionJson"`
	AssetIndex int    `json:"assetIndex"`
	AssetID    int    `json:"assetId"`
}

type CancelActionMetadata

type CancelActionMetadata struct {
	Coin string `json:"coin"`
	Oid  Int64  `json:"oid"`
}

CancelActionMetadata mirrors perps.proto CancelActionMetadata.

type Client

type Client struct {
	BaseURL      string
	HTTP         *http.Client
	UserAgent    string
	SessionID    string
	SessionToken string
	// OnUnauthenticated is notified only for a definite server rejection of
	// this session. It must not retry the request (especially mutations).
	OnUnauthenticated func()
}

Client calls Oku Connect endpoints.

func (*Client) Auth

func (c *Client) Auth(ctx context.Context, method string, req, resp any, authed bool) error

Auth calls an allowlisted AuthService method without exposing sensitive server errors.

func (*Client) Bridge

func (c *Client) Bridge(ctx context.Context, method string, req, resp any, authed bool) error

func (*Client) History

func (*Client) Onchain

func (c *Client) Onchain(ctx context.Context, method string, req, resp any, authed bool) error

func (*Client) Perps

func (c *Client) Perps(ctx context.Context, method string, req, resp any, authed bool) error

Perps calls a PerpsService method through the generated Connect client.

func (*Client) Portfolio

func (c *Client) Portfolio(ctx context.Context, method string, req, resp any, authed bool) error

Portfolio calls an allowlisted PortfolioService read through the generated Connect client.

func (*Client) Swap

func (c *Client) Swap(ctx context.Context, method string, req, resp any, authed bool) error

Swap calls a strictly allowlisted SimpleSwapServiceV2 method through the same generated Connect transport as the perps API.

func (*Client) TokenRPC

func (c *Client) TokenRPC(ctx context.Context, method string, req, resp any, authed bool) error

type ConfirmActionRequest

type ConfirmActionRequest struct {
	ActionID     string       `json:"actionId"`
	SignedAction SignedAction `json:"signedAction"`
}

type ConfirmActionResponse

type ConfirmActionResponse struct {
	Status       string `json:"status"`
	HlOid        Int64  `json:"hlOid"`
	ErrorMessage string `json:"errorMessage"`
}

type CreateActionRequest

type CreateActionRequest struct {
	Address string       `json:"address"`
	Params  ActionParams `json:"params"`
}

type EVMSignature

type EVMSignature struct {
	R string `json:"r"`
	S string `json:"s"`
	V Int64  `json:"v"`
}

type Error

type Error struct {
	Code    string // Connect code, e.g. "not_found", or "transport"
	Message string
	HTTP    int
	// Ambiguous is true when the request may have reached the server and
	// its effect is unknown (timeouts, dropped connections, 5xx).
	Ambiguous bool
	// contains filtered or unexported fields
}

Error is a Connect error or transport failure.

func AsError

func AsError(err error) (*Error, bool)

AsError extracts *Error.

func (*Error) Error

func (e *Error) Error() string

func (*Error) Unwrap

func (e *Error) Unwrap() error

type ExtendSessionResponse

type ExtendSessionResponse struct {
	Session *AccountSession `json:"session"`
}

type Fill

type Fill struct {
	Coin          string       `json:"coin"`
	Px            string       `json:"px"`
	Sz            string       `json:"sz"`
	Side          string       `json:"side"`
	Time          Int64        `json:"time"`
	Dir           string       `json:"dir"`
	ClosedPnl     string       `json:"closedPnl"`
	Hash          string       `json:"hash"`
	Oid           Int64        `json:"oid"`
	Crossed       bool         `json:"crossed"`
	Fee           string       `json:"fee"`
	Tid           Int64        `json:"tid"`
	FeeToken      string       `json:"feeToken"`
	StartPosition string       `json:"startPosition"`
	BuilderFee    string       `json:"builderFee,omitempty"`
	Kind          string       `json:"kind,omitempty"`
	TwapID        Int64        `json:"twapId,omitempty"`
	Origin        *OrderOrigin `json:"origin,omitempty"`
}

type FundingRate

type FundingRate struct {
	Time        Int64  `json:"time"`
	FundingRate string `json:"fundingRate"`
	Premium     string `json:"premium"`
}

type GetAccountBalancesResponse

type GetAccountBalancesResponse struct {
	SpotBalances         []SpotBalance     `json:"spotBalances"`
	SpotUsdcBalance      string            `json:"spotUsdcBalance"`
	SpotUsdcWithdrawable string            `json:"spotUsdcWithdrawable"`
	PerpsBalance         *PerpsBalance     `json:"perpsBalance"`
	Hip3Balances         []PerpsDexBalance `json:"hip3Balances"`
	AccountAbstraction   string            `json:"accountAbstraction"`
}

type GetActionResponse

type GetActionResponse struct {
	CliDeviceID  string `json:"cliDeviceId,omitempty"`
	ActionID     string `json:"actionId"`
	ActionType   string `json:"actionType"`
	State        string `json:"state"`
	HlOid        Int64  `json:"hlOid"`
	ErrorMessage string `json:"errorMessage"`
}

type GetBuilderFeeStatusResponse

type GetBuilderFeeStatusResponse struct {
	BuilderFeePpm               int    `json:"builderFeePpm"`
	BuilderFeeApproved          bool   `json:"builderFeeApproved"`
	BuilderAddress              string `json:"builderAddress"`
	BuilderFeeChargedPpm        int    `json:"builderFeeChargedPpm"`
	BuilderFeeApprovalTargetPpm int    `json:"builderFeeApprovalTargetPpm"`
}

type GetMarketFundingHistoryResponse

type GetMarketFundingHistoryResponse struct {
	Rates []FundingRate `json:"rates"`
}

type GetMarketPriceResponse

type GetMarketPriceResponse struct {
	Coin     string `json:"coin"`
	MarkPx   string `json:"markPx"`
	MidPx    string `json:"midPx"`
	OraclePx string `json:"oraclePx"`
}

type GetMarketsResponse

type GetMarketsResponse struct {
	Markets []Market `json:"markets"`
}

type GetOpenOrdersResponse

type GetOpenOrdersResponse struct {
	OpenOrders []Order `json:"openOrders"`
}

type GetPerpPositionsResponse

type GetPerpPositionsResponse struct {
	MarginSummary              *MarginSummary `json:"marginSummary"`
	CrossMarginSummary         *MarginSummary `json:"crossMarginSummary"`
	Withdrawable               string         `json:"withdrawable"`
	CrossMaintenanceMarginUsed string         `json:"crossMaintenanceMarginUsed"`
	Positions                  []Position     `json:"positions"`
}

type GetUserFillsResponse

type GetUserFillsResponse struct {
	Fills []Fill `json:"fills"`
}

type Int64

type Int64 int64

Int64 decodes protojson int64 (string) or JSON number.

func (Int64) MarshalJSON

func (i Int64) MarshalJSON() ([]byte, error)

MarshalJSON encodes as a decimal string (protojson form).

func (*Int64) UnmarshalJSON

func (i *Int64) UnmarshalJSON(b []byte) error

UnmarshalJSON implements json.Unmarshaler.

type LeverageActionMetadata

type LeverageActionMetadata struct {
	Coin     string `json:"coin"`
	Leverage int    `json:"leverage"`
	IsCross  bool   `json:"isCross"`
}

LeverageActionMetadata mirrors perps.proto LeverageActionMetadata.

type MarginActionMetadata

type MarginActionMetadata struct {
	Coin   string `json:"coin"`
	Amount string `json:"amount"`
}

MarginActionMetadata mirrors perps.proto MarginActionMetadata. Amount is a canonical signed decimal USDC string (negative removes margin).

type MarginSummary

type MarginSummary struct {
	AccountValue    string `json:"accountValue"`
	TotalNtlPos     string `json:"totalNtlPos"`
	TotalRawUsd     string `json:"totalRawUsd"`
	TotalMarginUsed string `json:"totalMarginUsed"`
}

type Market

type Market struct {
	Coin         string `json:"coin"`
	SzDecimals   int    `json:"szDecimals"`
	MaxLeverage  int    `json:"maxLeverage"`
	OnlyIsolated bool   `json:"onlyIsolated,omitempty"`
	AssetID      int    `json:"assetId"`
	MarkPx       string `json:"markPx,omitempty"`
	OraclePx     string `json:"oraclePx,omitempty"`
	MidPx        string `json:"midPx,omitempty"`
	Funding      string `json:"funding,omitempty"`
	OpenInterest string `json:"openInterest,omitempty"`
	PrevDayPx    string `json:"prevDayPx,omitempty"`
	DayNtlVlm    string `json:"dayNtlVlm,omitempty"`
	Premium      string `json:"premium,omitempty"`
	DisplayName  string `json:"displayName,omitempty"`
}

type Order

type Order struct {
	Coin             string       `json:"coin"`
	LimitPx          string       `json:"limitPx"`
	Origin           *OrderOrigin `json:"origin,omitempty"`
	Oid              Int64        `json:"oid"`
	Side             string       `json:"side"`
	Sz               string       `json:"sz"`
	Timestamp        Int64        `json:"timestamp"`
	OrigSz           string       `json:"origSz"`
	Cloid            string       `json:"cloid,omitempty"`
	OrderType        string       `json:"orderType"`
	TriggerPx        string       `json:"triggerPx,omitempty"`
	TriggerCondition string       `json:"triggerCondition,omitempty"`
	IsTrigger        bool         `json:"isTrigger"`
	ReduceOnly       bool         `json:"reduceOnly"`
	IsPositionTpsl   bool         `json:"isPositionTpsl"`
	AssetID          int          `json:"assetId"`
	Tif              string       `json:"tif,omitempty"`
	Children         []Order      `json:"children,omitempty"`
}

type OrderActionMetadata

type OrderActionMetadata struct {
	Coin        string `json:"coin"`
	Side        string `json:"side"`
	OrderType   string `json:"orderType"`
	Sz          string `json:"sz"`
	LimitPx     string `json:"limitPx,omitempty"`
	Tif         string `json:"tif,omitempty"`
	ReduceOnly  bool   `json:"reduceOnly,omitempty"`
	SlippageBps int    `json:"slippageBps,omitempty"`
}

OrderActionMetadata mirrors perps.proto OrderActionMetadata (subset used).

type OrderOrigin

type OrderOrigin struct {
	CliDeviceID   string `json:"cliDeviceId,omitempty"`
	CliDeviceName string `json:"cliDeviceName,omitempty"`
}

OrderOrigin mirrors perps.proto OrderOrigin. It is stamped server-side from device authentication; nil means external or unknown origin.

type PerpsBalance

type PerpsBalance struct {
	AccountValue string `json:"accountValue"`
	Withdrawable string `json:"withdrawable"`
	MarginUsed   string `json:"marginUsed"`
}

type PerpsDexBalance

type PerpsDexBalance struct {
	Dex          string `json:"dex"`
	AccountValue string `json:"accountValue"`
	Withdrawable string `json:"withdrawable"`
	MarginUsed   string `json:"marginUsed"`
}

type Position

type Position struct {
	Coin                string `json:"coin"`
	Szi                 string `json:"szi"`
	EntryPx             string `json:"entryPx"`
	PositionValue       string `json:"positionValue"`
	UnrealizedPnl       string `json:"unrealizedPnl"`
	ReturnOnEquity      string `json:"returnOnEquity"`
	LiquidationPx       string `json:"liquidationPx"`
	LeverageType        string `json:"leverageType"`
	LeverageValue       int    `json:"leverageValue"`
	MarginUsed          string `json:"marginUsed"`
	CumFundingAllTime   string `json:"cumFundingAllTime"`
	CumFundingSinceOpen string `json:"cumFundingSinceOpen"`
}

type PrivySessionExchangeResponse

type PrivySessionExchangeResponse struct {
	Session *AccountSession `json:"session"`
}

type ReconcileActionsResponse

type ReconcileActionsResponse struct {
	Actions []GetActionResponse `json:"actions"`
}

type SignedAction

type SignedAction struct {
	ActionJSON string       `json:"actionJson"`
	Nonce      Int64        `json:"nonce"`
	Signature  EVMSignature `json:"signature"`
}

type SpotBalance

type SpotBalance struct {
	Coin  string `json:"coin"`
	Token int    `json:"token"`
	Total string `json:"total"`
	Hold  string `json:"hold"`
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL