Gotrade Global Trading API

Programmatic US stock trading over a simple REST interface. Submit orders, monitor positions, and check buying power for any Gotrade Global account.

Overview

The Gotrade Trading API lets you place and manage US stock orders and read portfolio data directly, without using the mobile app. Every request is authenticated with a bearer token tied to a single account.

BASE URL

https://api.charlie.gotrade.admin.tr8.tech/api/b2c/v1

Programmatic trading

Submit buy and sell orders for US stocks via REST. Market, limit, stop, stop limit, and trailing stop order types, with extended hours and overnight trading support.

Portfolio monitoring

Query real-time open positions with unrealized P&L, cost basis, and intraday performance. Check account cash balances and available buying power.

Capabilities

Four endpoint groups cover order lifecycle, portfolio reads, pricing, and market data.

Category	Endpoints	Methods
Stock orders	3 endpoints	POST, GET, DELETE
Portfolio	2 endpoints	GET
Stock prices	1 endpoint	GET
Market data	3 endpoints	GET

Quickstart

Six steps to go from a new account to your first programmatic order.

1
Open a Gotrade account
Download the Gotrade app and register.
2
Complete KYC verification
Submit identity documents for regulatory compliance.
3
Fund your account
Deposit funds via wire transfer or a supported payment method.
4
Request trading API access
Contact your Gotrade account representative for API enablement.
5
Generate your API token
Navigate to Profile > API Key in the mobile app.
6
Start trading
Integrate the API endpoints and submit your first order.

Generate a token

API tokens are generated from within the Gotrade Global mobile app. Each account can have one active token at a time. Tokens are valid for 1 year and can be revoked at any time.

1
Open the Gotrade Global mobile app
Log in with your registered Gotrade account credentials.
2
Navigate to Profile > API Key
In your profile settings, locate the API Key management section.
3
Tap Generate Key
A new JWT token is created. Any previously active token is revoked immediately, so anything still using it stops working.
4
Store the token securely
Save it as a server-side environment variable or in a secrets manager. Token generation is rate limited to 5 requests per minute; token validity is 1 year.

Security reminder

Your token provides full trading access to your account. Never share it publicly, commit it to source control, or embed it in client-side code. Store it as a server-side environment variable or in a dedicated secrets manager.

Authentication

Include the token as a bearer token in the Authorization header of every request to the trading, portfolio, and market endpoints.

Request header format

Authorization: Bearer <your_b2c_token>

Authenticated request

Authorization: Bearer <your_b2c_token>

curl -X GET "https://api.charlie.gotrade.admin.tr8.tech/api/b2c/v1/portfolio/account-balance" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Accept: application/json"

Successful response

200 OK

{
  "data": {
    "cash_balance": "10000.00",
    "cash_available_for_trade": "8500.00",
    "currency": "USD"
  },
  "status": "success",
  "message": "Account balance retrieved successfully"
}

All requests must use HTTPS

HTTP requests are rejected. Ensure your client validates TLS certificates.

Create an order

Submit a new stock order. Supports market, limit, stop, stop limit, and trailing stop order types. Returns immediately with order status.

POST /api/b2c/v1/stock-orders/create

Request parameters

Parameter	Type	Required	Description
ticker	string	Yes	Stock ticker symbol, for example AAPL.
side	string	Yes	BUY, SELL, buy, or sell.
order_type	string	Yes	market, limit, stop, stop_limit, or trailing_stop.
quantity	number	Cond.	Number of shares. Required unless amount_cash is set.
amount_cash	number	No	Dollar amount for notional or fractional orders.
limit_price	number	Cond.	Required for limit and stop_limit. Minimum 1.
stop_price	number	Cond.	Required for stop, stop_limit, and trailing_stop. Minimum 1.
is_gtc	boolean	No	Good til cancelled. Defaults to a day order.
is_extended_hours	boolean	No	Allow execution during extended hours.
take_profit	number	No	Optional take profit price.
stop_loss	number	No	Optional stop loss price.
trail_price	number	No	Trail amount in dollars for trailing_stop orders.
trail_percent	number	No	Trail percentage for trailing_stop orders.

Example: market buy order

cURL

curl -X POST "https://api.charlie.gotrade.admin.tr8.tech/api/b2c/v1/stock-orders/create" \
  -H "Authorization: Bearer <your_b2c_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "ticker": "AAPL",
    "side": "BUY",
    "order_type": "market",
    "quantity": 1
  }'

Create order response

201 Created

{
  "data": {
    "stock": {
      "ticker": "AAPL",
      "name": "Apple",
      "full_name": "Apple Inc",
      "exchange": "NASDAQ",
      "currency": "USD",
      "fractionable": true,
      "shortable": false
    },
    "order": {
      "order_id": "61e69015-8549-4baf-b96e-00c55b5a28c6",
      "side": "BUY",
      "type": "MARKET",
      "status": "NEW",
      "quantity": "1.5",
      "cumulative_quantity": "0",
      "limit_price": 0,
      "time_in_force": "day",
      "extended_hours": false,
      "average_fill_price": "0",
      "fees": { "currency": "USD", "value": 0 },
      "created_at": "2026-02-27T06:00:00Z",
      "updated_at": "2026-02-27T06:00:00Z",
      "total_order_amount": null,
      "amount_cash": 0,
      "order_expires": "2026-02-28T06:00:00.000Z",
      "last_executed": null
    }
  },
  "status": "success",
  "message": "Order submitted successfully"
}

Order types and response

Five order types, each with its own required fields.

Market order

Executes immediately at the best available price. Supports fractional shares and dollar amount orders.

ticker, side, quantity or amount_cash

Limit order

Executes at your limit price or better. Required for extended hours and overnight sessions.

limit_price

Stop order

Becomes a market order once the stock reaches stop_price. Whole shares only.

stop_price

Stop limit order

Becomes a limit order once the stock reaches stop_price. Requires both prices.

stop_price, limit_price

Trailing stop order

Stop that follows the stock price. Set trail_price for a dollar offset or trail_percent for a percentage. Whole shares only.

stop_price, trail_price or trail_percent

List open orders

Lists the pending orders that are still working — not yet fully filled, cancelled, or expired. Each item carries the same stock and order shape as Get order status.

GET /api/b2c/v1/stock-orders

cURL

curl -X GET "https://api.charlie.gotrade.admin.tr8.tech/api/b2c/v1/stock-orders" \
  -H "Authorization: Bearer <your_b2c_token>"

200 OK

{
  "data": [
    {
      "stock": {
        "ticker": "AAPL",
        "name": "Apple",
        "full_name": "Apple Inc",
        "exchange": "NASDAQ",
        "currency": "USD",
        "fractionable": true,
        "shortable": false
      },
      "order": {
        "order_id": "61e69015-8549-4baf-b96e-00c55b5a28c6",
        "side": "BUY",
        "type": "LIMIT",
        "status": "NEW",
        "quantity": "1.5",
        "cumulative_quantity": "0",
        "limit_price": 150.0,
        "time_in_force": "day",
        "extended_hours": false,
        "average_fill_price": "0",
        "fees": { "currency": "USD", "value": 0 },
        "created_at": "2026-02-27T06:00:00Z",
        "updated_at": "2026-02-27T06:00:00Z",
        "amount_cash": 0,
        "last_executed": null
      }
    }
  ],
  "status": "success",
  "message": "Orders successfully retrieved"
}

Status and cancel

Retrieve the current status of a previously submitted order. The orderId is the UUID returned by the create endpoint.

GET /api/b2c/v1/stock-orders/{orderId}

cURL

curl -X GET "https://api.charlie.gotrade.admin.tr8.tech/api/b2c/v1/stock-orders/61e69015-8549-4baf-b96e-00c55b5a28c6" \
  -H "Authorization: Bearer <your_b2c_token>"

200 OK

{
  "data": {
    "stock": {
      "ticker": "AAPL",
      "name": "Apple",
      "full_name": "Apple Inc",
      "exchange": "NASDAQ",
      "currency": "USD",
      "fractionable": true,
      "shortable": false
    },
    "order": {
      "order_id": "61e69015-8549-4baf-b96e-00c55b5a28c6",
      "side": "BUY",
      "type": "MARKET",
      "status": "FILLED",
      "quantity": "1.5",
      "cumulative_quantity": "1.5",
      "limit_price": 0,
      "time_in_force": "day",
      "extended_hours": false,
      "average_fill_price": "178.50",
      "fees": { "currency": "USD", "value": 0 },
      "created_at": "2026-02-27T06:00:00Z",
      "updated_at": "2026-02-27T06:00:00Z",
      "total_order_amount": 267.75,
      "amount_cash": 0,
      "order_expires": "2026-02-28T06:00:00.000Z",
      "last_executed": "2026-02-27T06:00:30Z"
    }
  },
  "status": "success",
  "message": "Order details successfully retrieved"
}

Order status values

Status	Description
NEW	Order accepted and working. Also covers accepted and pending_new.
FILLED	Order fully executed.
PARTIAL_FILL	Order partially executed.
REJECTED	Order rejected by the broker.
CANCELED	Order cancelled or expired.

Cancel a pending order. Only orders that have not fully filled can be cancelled.

DELETE /api/b2c/v1/stock-orders/{orderId}

cURL

curl -X DELETE "https://api.charlie.gotrade.admin.tr8.tech/api/b2c/v1/stock-orders/61e69015-8549-4baf-b96e-00c55b5a28c6" \
  -H "Authorization: Bearer <your_b2c_token>"

200 OK

{
  "data": { "order_id": "61e69015-8549-4baf-b96e-00c55b5a28c6" },
  "status": "success",
  "message": "Order has been cancelled successfully"
}

Positions

Returns all currently held stock positions with real time market values and unrealized P&L. Pass is_extended_hours=true to include extended hours pricing data.

GET /api/b2c/v1/portfolio/open-positions

cURL

curl -X GET "https://api.charlie.gotrade.admin.tr8.tech/api/b2c/v1/portfolio/open-positions?is_extended_hours=false" \
  -H "Authorization: Bearer <your_b2c_token>"

200 OK

{
  "data": [
    {
      "ticker": "AAPL",
      "exchange": "NASDAQ",
      "currency": "USD",
      "quantity": "10.5",
      "avg_entry_price": "175.20",
      "market_value": "1873.50",
      "cost_basis": "1839.60",
      "unrealized_pl": "33.90",
      "unrealized_plpc": "0.0184",
      "unrealized_intraday_pl": "12.50",
      "unrealized_intraday_plpc": "0.0067"
    }
  ],
  "status": "success",
  "message": "Open positions retrieved successfully"
}

Position fields

Field	Description
ticker	Stock ticker symbol.
exchange	Listing exchange, for example NASDAQ or NYSE.
currency	Position currency (USD).
quantity	Number of shares held.
avg_entry_price	Weighted average purchase price per share.
market_value	Current total market value (quantity x current price).
cost_basis	Total cost of acquiring the position.
unrealized_pl	Unrealized profit or loss (market_value minus cost_basis).
unrealized_plpc	Unrealized P&L as a decimal percentage.
unrealized_intraday_pl	Today's unrealized P&L.
unrealized_intraday_plpc	Today's unrealized P&L as a decimal percentage.

Account balance

Returns the account's cash balance and available buying power in USD.

GET /api/b2c/v1/portfolio/account-balance

cURL

curl -X GET "https://api.charlie.gotrade.admin.tr8.tech/api/b2c/v1/portfolio/account-balance" \
  -H "Authorization: Bearer <your_b2c_token>"

200 OK

{
  "data": {
    "cash_balance": "10000.00",
    "cash_available_for_trade": "8500.00",
    "currency": "USD"
  },
  "status": "success",
  "message": "Account balance retrieved successfully"
}

Errors and security

All error responses follow a consistent JSON structure.

{
  "status": "error",
  "message": "Description of what went wrong"
}

HTTP status codes

Code	Meaning	When it occurs
200	OK	Successful GET and DELETE requests.
201	Created	Order created successfully.
400	Bad Request	Invalid parameters or a business rule violation, for example trading restricted, take profit or stop loss with extended hours, or insufficient buying power.
401	Unauthorized	Missing, expired, or invalid bearer token, or the account is not enabled for API access.
403	Forbidden	Buying stock is currently unavailable.
404	Not Found	Order, stock, or ticker not found.
500	Server Error	Internal error or an unhandled order submission failure.
502	Bad Gateway	Upstream broker request failed during cancel or status retrieval.

Security best practices

Use HTTPS for all requests
Store tokens in environment variables
Use a secrets manager in production
Rotate tokens periodically
Monitor API usage for anomalies

Don't

Embed tokens in client side code
Commit tokens to source control
Share tokens via unencrypted channels
Log token values in plain text
Use HTTP (non TLS) connections

Changelog

This document is maintained by Gotrade and updated as new API features become available. For the latest version, contact your account representative.

Version	Date	Changes
1.0	March 2026	Initial release with B2C Trading API documentation.