> ## Documentation Index > Fetch the complete documentation index at: https://docs.busha.io/llms.txt > Use this file to discover all available pages before exploring further. # Stock position detail > One position for the authenticated profile plus a page of the fills behind it, newest first. ## OpenAPI ````yaml https://raw.githubusercontent.com/bushaHQ/openapi/refs/heads/main/openapi-spec.yaml get /v1/stocks/portfolio/{symbol} openapi: 3.0.0 info: title: Busha API contact: email: developers@busha.co description: > ## Introduction The **Busha API** is designed to provide businesses with tools for borderless financial transactions and operations, enabling modern, global money management. It serves as the backbone for facilitating: - Creation and management of multi-currency balances - Retrieval of real-time cryptocurrency rates - Substantial data insights for business owners Whether you’re a product-driven fintech or a developer building integrations, this API significantly accelerates implementation while reducing financial complexities. For detailed guides on API integration, visit our [official documentation](). ## Authentication All API requests require a **Bearer Token** for authentication, passed in the `Authorization` header. Your authorization value is a base64 encoded value of your api key and your secret key. You can obtain API tokens via your Busha user or business account. Authentication is mandatory to ensure secure and authorized interactions with the API. The API keys from the dashboard provides a base64 encoding of the your authorization tokens. Your generated Key should look like this: `VURtNXhWcHueantkpaiewjo0S044MWsadfojienuoxRTiWDJaeWJaTGxxanZ3Ym10OU1RZnVWajVW=` Example Header: ``` curl Authorization: Bearer VURtNXhWcHueantkpaiewjo0S044MWsadfojienuoxRTiWDJaeWJaTGxxanZ3Ym10OU1RZnVWajVW= ``` ## Error Handling #Standardized error responses ensure predictable interactions. Errors are detailed for easy debugging and understanding: | **Error Code** | **HTTP Status Code** | **Description** | | --- | --- | --- | | `bad_request` | 400 | Invalid input or malformed request | | `unauthorized` | 401 | Invalid or missing authentication | | `not_found` | 404 | Resource not found | | `service_unavailable` | 503 | Server error | Basic Error Example: ``` json { "error": { "name": "bad_request", "message": "Invalid input data" } } ``` Schema Error Body Example: ``` json { "error": { "name": "bad_request", "message": "Invalid input data" }, "schema": { "reason": "The request body is defined as an object. However, it does not meet the schema requirements of the specification", "fix": "Ensure that the object being submitted, matches the schema correctly" } } ``` Field Error Body Example: ``` json { "error": { "name": "bad_request", "message": "Invalid input data" }, "fields": { "field1": [ { "reason": "The request body is defined as an object. However, it does not meet the schema requirements of the specification", }, ], "field2": [ { "reason": "The request body is defined as an object. However, it does not meet the schema requirements of the specification", } ], } } ``` ## Pagination Pagination uses cursors provided as: The API supports **cursor-based pagination** for endpoints with large datasets. Pagination uses a `next_cursor` and `previous_cursor` returned in the response. Example Response Format: ``` json { "current_entries_size": 10, "next_cursor": "base64_cursor_value", "previous_cursor": "base64_previous_cursor_value" } ``` ## Rate Limiting Rate limits determine how many API calls can be made in a rolling minute. This ensures fair and optimized use of system resources. The rate limits allowed by each resource will be provided with the header: ```curl x-rate-limit 100 ``` If this header does not exist, then the rate limit is set at a default 100 req/min Requests exceeding the allocated quota will receive a `429 Too Many Requests` response. ## Common Parameters Common parameters enhance consistency across endpoints: | **Parameter Name** | **Location** | **Description** | **Example** | | --- | --- | --- | --- | | `X-BU-PROFILE-ID` | Header | User profile identifier | `BUS_qwejinoiuiqw93ejjw` | | `id` | Path | Unique NanoID identifier | `dpt_jweqafajsndiun34fd` | | `cursor` | Query | Pagination cursor | `base64_cursor_string` | #### Paginated Response Example ``` json { "status": "success", "message": "Data retrieved", "pagination": { "next_cursor": "value_for_next_page", "current_entries_size": 20 }, "data": [...] } ``` version: 1.0.0 servers: - url: https://api.sandbox.busha.so description: Sandbox Environment - url: https://api.busha.io description: Production Environment security: [] tags: - name: Balances description: Handles account balances across different currencies. x-displayName: Balances - name: Bills description: Lorem Ipsum x-displayName: Bills - name: Cards description: Lorem Ipsum x-displayName: Cards - name: Cashback description: Main tag for cashback service endpoints x-displayName: Cashback - name: Currencies description: > Endpoints to manage supported currencies, their properties, and network details. x-displayName: Currencies - name: Customers x-internal: false description: Handle customer requests and responses x-displayName: Customers - name: Files description: Provides APIs to handle files upload x-displayName: Files - name: Futures description: Futures account management x-displayName: Futures - name: Insights description: Business analytics insights endpoints x-displayName: Insights - name: Mandate x-displayName: Mandate - name: Miscellaneous description: Provides auxiliary APIs to complement and enhance other services. x-displayName: Miscellaneous - name: News description: News article endpoints x-displayName: News - name: Pairs description: Access trading pair information and rates x-displayName: Pairs - name: PaymentLinks description: Payment Links x-displayName: PaymentLinks - name: PaymentRequests description: Payment request x-displayName: PaymentRequests - name: Pledges description: Customer-authorized pledge lifecycle APIs x-displayName: Pledges - name: PriceAlerts description: Price alert management endpoints x-displayName: PriceAlerts - name: Quotes description: Handle quotes requests and responses x-displayName: Quotes - name: Recipients x-displayName: Recipients - name: Stocks x-displayName: Stocks - name: Transactions x-displayName: Transactions - name: Transfers x-displayName: Transfers - name: Widget description: Widget operations x-displayName: Widget paths: /v1/stocks/portfolio/{symbol}: get: tags: - Stocks summary: Stock position detail description: > One position for the authenticated profile plus a page of the fills behind it, newest first. operationId: getStocksPosition parameters: - $ref: '#/components/parameters/ProfileHeader' - $ref: '#/components/parameters/StockSymbolPathParam' - $ref: '#/components/parameters/CursorQueryParams' - $ref: '#/components/parameters/LimitQueryParam' responses: '200': description: Position detail with recent activity. content: application/json: schema: allOf: - $ref: '#/components/schemas/CursorPagination' - type: object required: - data properties: data: $ref: '#/components/schemas/StockPositionDetail' 4XX: $ref: '#/components/responses/StocksError4XX' 5XX: $ref: '#/components/responses/StocksError5XX' security: - Auth: - stocks:read - api:read components: parameters: ProfileHeader: in: header name: X-BU-PROFILE-ID required: false description: User profile header schema: type: string example: BUS_YOK8tp5Zga01qOKEsqp07 StockSymbolPathParam: name: symbol in: path required: true description: The stock's display ticker (e.g. AAPL), never the vendor symbol. schema: type: string example: AAPL x-oapi-codegen-extra-tags: filter: trim|upper CursorQueryParams: name: cursor in: query description: The cursor schema: type: string format: string LimitQueryParam: name: limit in: query description: The number of items to return schema: type: integer example: 10 x-go-type: uint64 schemas: CursorPagination: allOf: - $ref: '#/components/schemas/BaseSchema' - type: object required: - pagination properties: pagination: type: object required: - current_entries_size properties: next_cursor: type: string example: MjAyNC0xMC0xNVQxMTowNTo1My45NTkxNDErMDE6MDA= current_entries_size: type: integer example: 20 previous_cursor: type: string example: MjAyNC0xMC0xNVQxMDowNTo1My45NTIxQjE3MDE6MDA= StockPositionDetail: type: object required: - position - activities properties: position: $ref: '#/components/schemas/StockPosition' activities: type: array items: $ref: '#/components/schemas/StockActivity' BaseSchema: description: General response Values type: object required: - status - message properties: status: type: string x-order: 1 x-go-type: string enum: - success - error example: success message: type: string x-order: 2 example: message for success StockPosition: type: object required: - symbol - name - display_ticker - tokens - value - cost_basis - is_market_open - buy_supported - sell_supported properties: symbol: type: string example: AAPL x-order: 1 name: type: string example: Apple x-order: 2 display_ticker: type: string example: AAPL x-order: 3 logo_url: allOf: - $ref: '#/components/schemas/UrlField' x-order: 4 tokens: allOf: - $ref: '#/components/schemas/Decimal' description: Token quantity held, 18 decimal places. x-order: 5 price: allOf: - $ref: '#/components/schemas/AmountWithCurrency' description: Display (mid) token price; absent when no price is available. x-order: 6 value: allOf: - $ref: '#/components/schemas/AmountWithCurrency' description: tokens times price; zero when there is no price. x-order: 7 cost_basis: allOf: - $ref: '#/components/schemas/AmountWithCurrency' description: Total paid for the position under average-cost accounting. x-order: 8 average_price: allOf: - $ref: '#/components/schemas/AmountWithCurrency' description: >- Average entry price (cost_basis / tokens); absent when there is no position. x-order: 9 average_price_change: allOf: - $ref: '#/components/schemas/PriceChange' description: >- Change between current price and average entry price; absent when no position or unpriced. x-order: 10 unrealized_pnl: allOf: - $ref: '#/components/schemas/PriceChange' description: >- All-time return; amount is total P&L, percent is return %. Absent when the position is unpriced. x-order: 11 change_24h: allOf: - $ref: '#/components/schemas/PriceChange' description: 24h price change (absolute and percent); absent when no 24h history. x-order: 13 is_market_open: type: boolean description: > Whether this stock's market is open right now, from the persisted book-meta snapshot (the inverse of its closed state, so it is off-hours aware). Falls back to the live venue observation until the first snapshot is written. x-order: 14 buy_supported: type: boolean description: Whether a buy can be placed; tradeable symbol with the market open. x-order: 15 sell_supported: type: boolean description: Whether a sell can be placed; tradeable symbol with the market open. x-order: 16 StockActivity: type: object required: - id - symbol - action - tokens - amount - unit_price - status - created_at properties: id: type: string example: SBE_1a2b3c x-order: 1 symbol: type: string example: AAPL x-order: 2 action: type: string enum: - buy - sell x-order: 3 tokens: allOf: - $ref: '#/components/schemas/Decimal' x-order: 4 amount: allOf: - $ref: '#/components/schemas/AmountWithCurrency' description: Settlement value of the fill. x-order: 5 unit_price: allOf: - $ref: '#/components/schemas/AmountWithCurrency' description: Executed price per token, spread included. x-order: 6 funding_currency: type: string example: NGN x-order: 7 funding_amount: allOf: - $ref: '#/components/schemas/Decimal' x-order: 8 status: type: string enum: - completed example: completed x-order: 9 created_at: type: string format: date-time x-order: 10 ErrorResponse: type: object required: - error properties: error: type: object required: - name - message properties: name: type: string x-order: 40 example: bad_request message: type: string example: Invalid Request fields: type: object schema: type: array items: type: object example: error: name: bad_request message: Invalid Request UrlField: type: string example: https://example.com format: url description: A valid url x-oapi-codegen-extra-tags: validate: required|url Decimal: type: string description: decimal value example: '100' x-go-type: decimal.Decimal x-go-type-import: path: github.com/shopspring/decimal name: decimal AmountWithCurrency: type: object description: Amount with currency required: - amount - currency properties: amount: $ref: '#/components/schemas/Decimal' currency: $ref: '#/components/schemas/Currency' PriceChange: type: object description: Price change with currency, absolute amount and percentage. properties: currency: allOf: - $ref: '#/components/schemas/Currency' description: Currency the amount is denominated in. amount: allOf: - $ref: '#/components/schemas/Decimal' description: Absolute change (current - reference). percent: allOf: - $ref: '#/components/schemas/Decimal' description: Percentage change, e.g. 1.25 = +1.25%. Currency: type: string x-order: 20 example: BTC format: string maxLength: 10 minLength: 1 description: A valid currency x-oapi-codegen-extra-tags: validate: required|min_len:1|max_len:10 filter: trim|upper responses: StocksError4XX: description: Error from customer resource. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: default: $ref: '#/components/examples/DefaultError' not_found_error: $ref: '#/components/examples/NotFoundError' unauthorized_error: $ref: '#/components/examples/UnAuthorizedError' request_validation_error: $ref: '#/components/examples/RequestValidationError' schema_validation_error: $ref: '#/components/examples/SchemaValidationError' StocksError5XX: description: Server error when processing the stocks request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal_server_error: $ref: '#/components/examples/InternalServerError' service_unavailable_error: $ref: '#/components/examples/ServiceUnavailableError' examples: DefaultError: description: Default error value: error: name: bad_request message: Invalid request NotFoundError: description: Not Found error value: error: name: resource_not_found message: Resource Not Found UnAuthorizedError: description: Unauthorized Error value: error: name: unauthorized message: Unauthorized request RequestValidationError: description: Request Validation error example value: error: name: request_validation message: Validation error fields: field1: - reason: One of target and source amount must be set field2: - reason: One of target and source amount must be set SchemaValidationError: description: Schema validation error example value: error: name: schema_validation message: Error Validating Requests schema: - reason: >- The request body is defined as an object. However, it does not meet the schema requirements of the specification fix: >- Ensure that the object being submitted, matches the schema correctly schema_validation_error: - 'minLength: got 3, want 12' InternalServerError: description: Internal Server Error value: error: name: internal_server_error message: Internal Server Error ServiceUnavailableError: description: Service Unavailable Error value: error: name: service_unavailable message: Service Unavailable securitySchemes: Auth: type: http scheme: bearer description: Bearer Authentication ````