OANDA Accounts API

openapi: 3.2.0
info:
  title: OANDA v20 REST Accounts API
  description: The full OANDA v20 REST API Specification. This specification defines how to interact with v20 Accounts, Trades, Orders, Pricing and more.
  contact:
    name: OANDA API Support
    url: http://developer.oanda.com/rest-live-v20/introduction/
    email: api@oanda.com
  license:
    name: MIT
    url: https://github.com/oanda/v20-openapi/blob/master/LICENSE.txt
  version: 3.0.25
servers:
- url: /v3
tags:
- name: Accounts
paths:
  /accounts/{accountID}/positions:
    get:
      summary: List Positions
      description: List all Positions for an Account. The Positions returned are for every instrument that has had a position during the lifetime of an the Account.
      operationId: listPositions
      parameters:
      - $ref: '#/components/parameters/authorizationHeaderParam'
      - $ref: '#/components/parameters/accountIDPathParam'
      responses:
        '200':
          description: The Account's Positions are provided.
          headers:
            RequestID:
              description: The unique identifier generated for the request
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  positions:
                    type: array
                    description: The list of Account Positions.
                    items:
                      $ref: '#/components/schemas/Position'
                  lastTransactionID:
                    type: string
                    description: The ID of the most recent Transaction created for the Account
                    format: String representation of the numerical OANDA-assigned TransactionID
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '405':
          $ref: '#/components/responses/405'
      tags:
      - Accounts
  /accounts/{accountID}/openPositions:
    get:
      summary: Open Positions
      description: List all open Positions for an Account. An open Position is a Position in an Account that currently has a Trade opened for it.
      operationId: listOpenPositions
      parameters:
      - $ref: '#/components/parameters/authorizationHeaderParam'
      - $ref: '#/components/parameters/accountIDPathParam'
      responses:
        '200':
          description: The Account's open Positions are provided.
          headers:
            RequestID:
              description: The unique identifier generated for the request
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  positions:
                    type: array
                    description: The list of open Positions in the Account.
                    items:
                      $ref: '#/components/schemas/Position'
                  lastTransactionID:
                    type: string
                    description: The ID of the most recent Transaction created for the Account
                    format: String representation of the numerical OANDA-assigned TransactionID
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '405':
          $ref: '#/components/responses/405'
      tags:
      - Accounts
  /accounts/{accountID}/positions/{instrument}:
    get:
      summary: Instrument Position
      description: Get the details of a single Instrument's Position in an Account. The Position may by open or not.
      operationId: getPosition
      parameters:
      - $ref: '#/components/parameters/authorizationHeaderParam'
      - $ref: '#/components/parameters/accountIDPathParam'
      - $ref: '#/components/parameters/instrumentNamePathParam'
      responses:
        '200':
          description: The Position is provided.
          headers:
            RequestID:
              description: The unique identifier generated for the request
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  position:
                    $ref: '#/components/schemas/Position'
                  lastTransactionID:
                    type: string
                    description: The ID of the most recent Transaction created for the Account
                    format: String representation of the numerical OANDA-assigned TransactionID
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '405':
          $ref: '#/components/responses/405'
      tags:
      - Accounts
  /accounts/{accountID}/positions/{instrument}/close:
    put:
      summary: Close Position
      description: Closeout the open Position for a specific instrument in an Account.
      operationId: closePosition
      parameters:
      - $ref: '#/components/parameters/authorizationHeaderParam'
      - $ref: '#/components/parameters/acceptDatetimeFormatHeaderParam'
      - $ref: '#/components/parameters/accountIDPathParam'
      - $ref: '#/components/parameters/instrumentNamePathParam'
      responses:
        '200':
          description: The Position closeout request has been successfully processed.
          headers:
            Location:
              description: A link to the Position that was just closed out
              schema:
                type: string
            RequestID:
              description: The unique identifier generated for the request
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  longOrderCreateTransaction:
                    $ref: '#/components/schemas/MarketOrderTransaction'
                  longOrderFillTransaction:
                    $ref: '#/components/schemas/OrderFillTransaction'
                  longOrderCancelTransaction:
                    $ref: '#/components/schemas/OrderCancelTransaction'
                  shortOrderCreateTransaction:
                    $ref: '#/components/schemas/MarketOrderTransaction'
                  shortOrderFillTransaction:
                    $ref: '#/components/schemas/OrderFillTransaction'
                  shortOrderCancelTransaction:
                    $ref: '#/components/schemas/OrderCancelTransaction'
                  relatedTransactionIDs:
                    type: array
                    description: The IDs of all Transactions that were created while satisfying the request.
                    items:
                      type: string
                      description: The unique Transaction identifier within each Account.
                      format: String representation of the numerical OANDA-assigned TransactionID
                  lastTransactionID:
                    type: string
                    description: The ID of the most recent Transaction created for the Account
                    format: String representation of the numerical OANDA-assigned TransactionID
        '400':
          description: The Parameters provided that describe the Position closeout are invalid.
          content:
            application/json:
              schema:
                type: object
                properties:
                  longOrderRejectTransaction:
                    $ref: '#/components/schemas/MarketOrderRejectTransaction'
                  shortOrderRejectTransaction:
                    $ref: '#/components/schemas/MarketOrderRejectTransaction'
                  relatedTransactionIDs:
                    type: array
                    description: The IDs of all Transactions that were created while satisfying the request.
                    items:
                      type: string
                      description: The unique Transaction identifier within each Account.
                      format: String representation of the numerical OANDA-assigned TransactionID
                  lastTransactionID:
                    type: string
                    description: The ID of the most recent Transaction created for the Account
                    format: String representation of the numerical OANDA-assigned TransactionID
                  errorCode:
                    type: string
                    description: The code of the error that has occurred. This field may not be returned for some errors.
                  errorMessage:
                    type: string
                    description: The human-readable description of the error that has occurred.
        '401':
          $ref: '#/components/responses/401'
        '404':
          description: The Account or one or more of the Positions specified does not exist.
          content:
            application/json:
              schema:
                type: object
                properties:
                  longOrderRejectTransaction:
                    $ref: '#/components/schemas/MarketOrderRejectTransaction'
                  shortOrderRejectTransaction:
                    $ref: '#/components/schemas/MarketOrderRejectTransaction'
                  relatedTransactionIDs:
                    type: array
                    description: The IDs of all Transactions that were created while satisfying the request. Only present if the Account exists.
                    items:
                      type: string
                      description: The unique Transaction identifier within each Account.
                      format: String representation of the numerical OANDA-assigned TransactionID
                  lastTransactionID:
                    type: string
                    description: The ID of the most recent Transaction created for the Account. Only present if the Account exists.
                    format: String representation of the numerical OANDA-assigned TransactionID
                  errorCode:
                    type: string
                    description: The code of the error that has occurred. This field may not be returned for some errors.
                  errorMessage:
                    type: string
                    description: The human-readable description of the error that has occurred.
        '405':
          $ref: '#/components/responses/405'
      tags:
      - Accounts
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                longUnits:
                  type: string
                  description: Indication of how much of the long Position to closeout. Either the string "ALL", the string "NONE", or a DecimalNumber representing how many units of the long position to close using a PositionCloseout MarketOrder. The units specified must always be positive.
                longClientExtensions:
                  $ref: '#/components/schemas/ClientExtensions'
                shortUnits:
                  type: string
                  description: Indication of how much of the short Position to closeout. Either the string "ALL", the string "NONE", or a DecimalNumber representing how many units of the short position to close using a PositionCloseout MarketOrder. The units specified must always be positive.
                shortClientExtensions:
                  $ref: '#/components/schemas/ClientExtensions'
        description: Representation of how to close the position
        required: true
  /accounts/{accountID}/trades:
    get:
      summary: List Trades
      description: Get a list of Trades for an Account
      operationId: listTrades
      parameters:
      - $ref: '#/components/parameters/authorizationHeaderParam'
      - $ref: '#/components/parameters/acceptDatetimeFormatHeaderParam'
      - $ref: '#/components/parameters/accountIDPathParam'
      - name: ids
        description: List of Trade IDs to retrieve.
        in: query
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
            format: The string representation of the OANDA-assigned TradeID. OANDA-assigned TradeIDs are positive integers, and are derived from the TransactionID of the Transaction that opened the Trade.
      - name: state
        description: The state to filter the requested Trades by.
        in: query
        schema:
          type: string
      - name: instrument
        description: The instrument to filter the requested Trades by.
        in: query
        schema:
          type: string
          format: A string containing the base currency and quote currency delimited by a "_".
      - name: count
        description: The maximum number of Trades to return.
        in: query
        schema:
          type: integer
      - name: beforeID
        description: The maximum Trade ID to return. If not provided the most recent Trades in the Account are returned.
        in: query
        schema:
          type: string
          format: The string representation of the OANDA-assigned TradeID. OANDA-assigned TradeIDs are positive integers, and are derived from the TransactionID of the Transaction that opened the Trade.
      responses:
        '200':
          description: The list of Trades requested
          headers:
            Link:
              description: A link to the next page of Trades if the results were paginated
              schema:
                type: string
            RequestID:
              description: The unique identifier generated for the request
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  trades:
                    type: array
                    description: The list of Trade detail objects
                    items:
                      $ref: '#/components/schemas/Trade'
                  lastTransactionID:
                    type: string
                    description: The ID of the most recent Transaction created for the Account
                    format: String representation of the numerical OANDA-assigned TransactionID
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '405':
          $ref: '#/components/responses/405'
      tags:
      - Accounts
  /accounts/{accountID}/openTrades:
    get:
      summary: List Open Trades
      description: Get the list of open Trades for an Account
      operationId: listOpenTrades
      parameters:
      - $ref: '#/components/parameters/authorizationHeaderParam'
      - $ref: '#/components/parameters/acceptDatetimeFormatHeaderParam'
      - $ref: '#/components/parameters/accountIDPathParam'
      responses:
        '200':
          description: The Account's list of open Trades is provided
          headers:
            RequestID:
              description: The unique identifier generated for the request
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  trades:
                    type: array
                    description: The Account's list of open Trades
                    items:
                      $ref: '#/components/schemas/Trade'
                  lastTransactionID:
                    type: string
                    description: The ID of the most recent Transaction created for the Account
                    format: String representation of the numerical OANDA-assigned TransactionID
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '405':
          $ref: '#/components/responses/405'
      tags:
      - Accounts
  /accounts/{accountID}/trades/{tradeSpecifier}:
    get:
      summary: Trade Details
      description: Get the details of a specific Trade in an Account
      operationId: getTrade
      parameters:
      - $ref: '#/components/parameters/authorizationHeaderParam'
      - $ref: '#/components/parameters/acceptDatetimeFormatHeaderParam'
      - $ref: '#/components/parameters/accountIDPathParam'
      - $ref: '#/components/parameters/tradeSpecifierPathParam'
      responses:
        '200':
          description: The details for the requested Trade is provided
          headers:
            RequestID:
              description: The unique identifier generated for the request
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  trade:
                    $ref: '#/components/schemas/Trade'
                  lastTransactionID:
                    type: string
                    description: The ID of the most recent Transaction created for the Account
                    format: String representation of the numerical OANDA-assigned TransactionID
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '405':
          $ref: '#/components/responses/405'
      tags:
      - Accounts
  /accounts/{accountID}/trades/{tradeSpecifier}/close:
    put:
      summary: Close Trade
      description: Close (partially or fully) a specific open Trade in an Account
      operationId: closeTrade
      parameters:
      - $ref: '#/components/parameters/authorizationHeaderParam'
      - $ref: '#/components/parameters/acceptDatetimeFormatHeaderParam'
      - $ref: '#/components/parameters/accountIDPathParam'
      - $ref: '#/components/parameters/tradeSpecifierPathParam'
      responses:
        '200':
          description: The Trade has been closed as requested
          headers:
            RequestID:
              description: The unique identifier generated for the request
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  orderCreateTransaction:
                    $ref: '#/components/schemas/MarketOrderTransaction'
                  orderFillTransaction:
                    $ref: '#/components/schemas/OrderFillTransaction'
                  orderCancelTransaction:
                    $ref: '#/components/schemas/OrderCancelTransaction'
                  relatedTransactionIDs:
                    type: array
                    description: The IDs of all Transactions that were created while satisfying the request.
                    items:
                      type: string
                      description: The unique Transaction identifier within each Account.
                      format: String representation of the numerical OANDA-assigned TransactionID
                  lastTransactionID:
                    type: string
                    description: The ID of the most recent Transaction created for the Account
                    format: String representation of the numerical OANDA-assigned TransactionID
        '400':
          description: The Trade cannot be closed as requested.
          content:
            application/json:
              schema:
                type: object
                properties:
                  orderRejectTransaction:
                    $ref: '#/components/schemas/MarketOrderRejectTransaction'
                  errorCode:
                    type: string
                    description: The code of the error that has occurred. This field may not be returned for some errors.
                  errorMessage:
                    type: string
                    description: The human-readable description of the error that has occurred.
        '401':
          $ref: '#/components/responses/401'
        '404':
          description: The Account or Trade specified does not exist.
          content:
            application/json:
              schema:
                type: object
                properties:
                  orderRejectTransaction:
                    $ref: '#/components/schemas/MarketOrderRejectTransaction'
                  lastTransactionID:
                    type: string
                    description: The ID of the most recent Transaction created for the Account. Only present if the Account exists.
                    format: String representation of the numerical OANDA-assigned TransactionID
                  relatedTransactionIDs:
                    type: array
                    description: The IDs of all Transactions that were created while satisfying the request. Only present if the Account exists.
                    items:
                      type: string
                      description: The unique Transaction identifier within each Account.
                      format: String representation of the numerical OANDA-assigned TransactionID
                  errorCode:
                    type: string
                    description: The code of the error that has occurred. This field may not be returned for some errors.
                  errorMessage:
                    type: string
                    description: The human-readable description of the error that has occurred.
        '405':
          $ref: '#/components/responses/405'
      tags:
      - Accounts
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                units:
                  type: string
                  description: Indication of how much of the Trade to close. Either the string "ALL" (indicating that all of the Trade should be closed), or a DecimalNumber representing the number of units of the open Trade to Close using a TradeClose MarketOrder. The units specified must always be positive, and the magnitude of the value cannot exceed the magnitude of the Trade's open units.
        description: Details of how much of the open Trade to close.
        required: true
  /accounts/{accountID}/trades/{tradeSpecifier}/clientExtensions:
    put:
      summary: Set Trade Client Extensions
      description: Update the Client Extensions for a Trade. Do not add, update, or delete the Client Extensions if your account is associated with MT4.
      operationId: setTradeClientExtensions
      parameters:
      - $ref: '#/components/parameters/authorizationHeaderParam'
      - $ref: '#/components/parameters/acceptDatetimeFormatHeaderParam'
      - $ref: '#/components/parameters/accountIDPathParam'
      - $ref: '#/components/parameters/tradeSpecifierPathParam'
      responses:
        '200':
          description: The Trade's Client Extensions have been updated as requested.
          headers:
            RequestID:
              description: The unique identifier generated for the request
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  tradeClientExtensionsModifyTransaction:
                    $ref: '#/components/schemas/TradeClientExtensionsModifyTransaction'
                  relatedTransactionIDs:
                    type: array
                    description: The IDs of all Transactions that were created while satisfying the request.
                    items:
                      type: string
                      description: The unique Transaction identifier within each Account.
                      format: String representation of the numerical OANDA-assigned TransactionID
                  lastTransactionID:
                    type: string
                    description: The ID of the most recent Transaction created for the Account
                    format: String representation of the numerical OANDA-assigned TransactionID
        '400':
          description: The Trade's Client Extensions cannot be modified as requested.
          content:
            application/json:
              schema:
                type: object
                properties:
                  tradeClientExtensionsModifyRejectTransaction:
                    $ref: '#/components/schemas/TradeClientExtensionsModifyRejectTransaction'
                  lastTransactionID:
                    type: string
                    description: The ID of the most recent Transaction created for the Account.
                    format: String representation of the numerical OANDA-assigned TransactionID
                  relatedTransactionIDs:
                    type: array
                    description: The IDs of all Transactions that were created while satisfying the request.
                    items:
                      type: string
                      description: The unique Transaction identifier within each Account.
                      format: String representation of the numerical OANDA-assigned TransactionID
                  errorCode:
                    type: string
                    description: The code of the error that has occurred. This field may not be returned for some errors.
                  errorMessage:
                    type: string
                    description: The human-readable description of the error that has occurred.
        '401':
          $ref: '#/components/responses/401'
        '404':
          description: The Account or Trade specified does not exist.
          content:
            application/json:
              schema:
                type: object
                properties:
                  tradeClientExtensionsModifyRejectTransaction:
                    $ref: '#/components/schemas/TradeClientExtensionsModifyRejectTransaction'
                  lastTransactionID:
                    type: string
                    description: The ID of the most recent Transaction created for the Account. Only present if the Account exists.
                    format: String representation of the numerical OANDA-assigned TransactionID
                  relatedTransactionIDs:
                    type: array
                    description: The IDs of all Transactions that were created while satisfying the request. Only present if the Account exists.
                    items:
                      type: string
                      description: The unique Transaction identifier within each Account.
                      format: String representation of the numerical OANDA-assigned TransactionID
                  errorCode:
                    type: string
                    description: The code of the error that has occurred. This field may not be returned for some errors.
                  errorMessage:
                    type: string
                    description: The human-readable description of the error that has occurred.
        '405':
          $ref: '#/components/responses/405'
      tags:
      - Accounts
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                clientExtensions:
                  $ref: '#/components/schemas/ClientExtensions'
        description: Details of how to modify the Trade's Client Extensions.
        required: true
  /accounts/{accountID}/trades/{tradeSpecifier}/orders:
    put:
      summary: Set Dependent Orders
      description: Create, replace and cancel a Trade's dependent Orders (Take Profit, Stop Loss and Trailing Stop Loss) through the Trade itself
      operationId: setTradeDependentOrders
      parameters:
      - $ref: '#/components/parameters/authorizationHeaderParam'
      - $ref: '#/components/parameters/acceptDatetimeFormatHeaderParam'
      - $ref: '#/components/parameters/accountIDPathParam'
      - $ref: '#/components/parameters/tradeSpecifierPathParam'
      responses:
        '200':
          description: The Trade's dependent Orders have been modified as requested.
          headers:
            RequestID:
              description: The unique identifier generated for the request
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  takeProfitOrderCancelTransaction:
                    $ref: '#/components/schemas/OrderCancelTransaction'
                  takeProfitOrderTransaction:
                    $ref: '#/components/schemas/TakeProfitOrderTransaction'
                  takeProfitOrderFillTransaction:
                    $ref: '#/components/schemas/OrderFillTransaction'
                  takeProfitOrderCreatedCancelTransaction:
                    $ref: '#/components/schemas/OrderCancelTransaction'
                  stopLossOrderCancelTransaction:
                    $ref: '#/components/schemas/OrderCancelTransaction'
                  stopLossOrderTransaction:
                    $ref: '#/components/schemas/StopLossOrderTransaction'
                  stopLossOrderFillTransaction:
                    $ref: '#/components/schemas/OrderFillTransaction'
                  stopLossOrderCreatedCancelTransaction:
                    $ref: '#/components/schemas/OrderCancelTransaction'
                  trailingStopLossOrderCancelTransaction:
                    $ref: '#/components/schemas/OrderCancelTransaction'
                  trailingStopLossOrderTransaction:
                    $ref: '#/components/schemas/TrailingStopLossOrderTransaction'
                  relatedTransactionIDs:
                    type: array
                    description: The IDs of all Transactions that were created while satisfying the request.
                    items:
                      type: string
                      description: The unique Transaction identifier within each Account.
                      format: String representation of the numerical OANDA-assigned TransactionID
                  lastTransactionID:
                    type: string
                    description: The ID of the most recent Transaction created for the Account
                    format: String representation of the numerical OANDA-assigned TransactionID
        '400':
          description: The Trade's dependent Orders cannot be modified as requested.
          content:
            application/json:
              schema:
                type: object
                properties:
                  takeProfitOrderCancelRejectTransaction:
                    $ref: '#/components/schemas/OrderCancelRejectTransaction'
                  takeProfitOrderRejectTransaction:
                    $ref: '#/components/schemas/TakeProfitOrderRejectTransaction'
                  stopLossOrderCancelRejectTransaction:
                    $ref: '#/components/schemas/OrderCancelRejectTransaction'
                  stopLossOrderRejectTransaction:
                    $ref: '#/components/schemas/StopLossOrderRejectTransaction'
                  trailingStopLossOrderCancelRejectTransaction:
                    $ref: '#/components/schemas/OrderCancelRejectTransaction'
                  trailingStopLossOrderRejectTransaction:
                    $ref: '#/components/schemas/TrailingStopLossOrderRejectTransaction'
                  lastTransactionID:
                    type: string
                    description: The ID of the most recent Transaction created for the Account.
                    format: String representation of the numerical OANDA-assigned TransactionID
                  relatedTransactionIDs:
                    type: array
                    description: The IDs of all Transactions that were created while satisfying the request.
                    items:
                      type: string
                      description: The unique Transaction identifier within each Account.
                      format: String representation of the numerical OANDA-assigned TransactionID
                  errorCode:
                    type: string
                    description: The code of the error that has occurred. This field may not be returned for some errors.
                  errorMessage:
                    type: string
                    description: The human-readable description of the error that has occurred.
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '405':
          $ref: '#/

# --- truncated at 32 KB (349 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/oanda/refs/heads/main/openapi/oanda-accounts-api-openapi.yml