> ## Documentation Index > Fetch the complete documentation index at: https://docs.services.payward.com/llms.txt > Use this file to discover all available pages before exploring further. # List portfolio transactions > Lists account portfolio transactions with optional filters for type, asset, status, transaction ID, originating reference, time range, and sort direction. Results are cursor-paginated. Results are ordered newest first by default; set `sort_direction=asc` for oldest first. Page tokens are valid for up to 24 hours. A page can contain fewer than `page_size` matching transactions, including no transactions, while still returning `next_page_token`; continue until the token is absent. Transactions can appear asynchronously. To discover new activity, poll this operation with the applicable `types` filters and an appropriate time range, omitting `statuses` or including `in_progress` while a transaction is being processed. For a transfer created by `POST /v1/transfers`, use `types=transfer` and the `from` account from the create request. For an accepted derivatives transfer created by `POST /v1/accounts/{account_id}/transfers/derivatives`, use `types=transfer` and the `account_id` from the request path. The `transfer_id` returned by either create operation is the `id` in a `reference` with `kind=transfer`. Once the transaction appears, that reference can be submitted in `references` for deterministic subsequent lookup. A transfer may appear with `status=in_progress` before it reaches the terminal `successful` or `failed` status; filtering only by `successful` can therefore hide a newly materialized transfer. The first Portfolio response after a transfer is created may contain no matching transaction even when a generic transfer has `status=complete` or a derivatives transfer has `status=accepted`; continue polling until the transaction is present. For deposits and withdrawals, `reference.kind=funding` identifies the originating funding transaction. For deposits, it is not the deposit destination or a payment reference from bank-transfer instructions; those values describe how to make the payment and are not accepted by `references`. For withdrawals, use `types=withdrawal` and, when the originating funding identifier is known, submit it in `references` as the `id` with `kind=funding`. Poll with `statuses` omitted until the withdrawal appears, then continue polling without that filter until its status is terminal: `successful` or `failed`. Filtering only by `in_progress` is useful for discovering pending withdrawals, but it excludes terminal results and must be removed or changed before polling for completion. Once a funding transaction appears, its reference can be used for deterministic subsequent lookup. The returned Portfolio transaction `id` uses the `TX` namespace and is distinct from the funding identifier in `reference.id`. ## OpenAPI ````yaml https://dsct1ci24fgcu.cloudfront.net/prod/merged/openapi.json get /v1/accounts/{account_id}/portfolio/transactions openapi: 3.1.0 info: title: PWS Public API version: '1' description: >- Integrate with Payward Services to onboard users, manage accounts and funds, trade assets, and receive event notifications. contact: name: Payward Services servers: - url: https://api.services.payward.com security: [] tags: - name: Assets description: List the assets PWS is willing to swap. x-displayName: Assets - name: Conversions description: >- Rule-driven and on-demand fiat ↔ crypto value movement, including conversion rules and deposits. x-displayName: Conversions - name: Earn description: >- Manage Auto Earn preferences and retrieve allocation and reward information. x-displayName: Earn - name: Funding description: >- Discover deposit and withdrawal options, manage deposit addresses, and move funds between accounts. x-displayName: Funding - name: Derivative transfers description: >- Move funds between an account's spot balance and the same owner's futures balance. x-displayName: Derivative transfers - name: Portfolio description: 'Inspect a customer''s portfolio: balances, valuations, and transactions.' x-displayName: Portfolio - name: Ramp description: >- Support Ramp flows with discovery, quotes, limits, and hosted checkout experiences. x-displayName: Ramp - name: Reports description: Settlement and reconciliation reports for the partner. x-displayName: Reports - name: Swaps description: Account-funded quotes that lock a price until they expire or are executed. x-displayName: Swaps - name: Onchain quotes description: Wallet-funded quotes that return the data needed to settle onchain. x-displayName: Onchain quotes - name: Price trigger swaps description: Swaps that wait for a target price before submitting a trade. x-displayName: Price trigger swaps - name: Travel Rule verifications description: Travel Rule address ownership verification flows. x-displayName: Travel Rule verifications - name: Users description: >- User onboarding and status flows that the partner manages. - **Create User** provisions an account-owned user from an external reference and optional email. - **Get User** retrieves the user's profile, verification status, and required actions. Use the returned user `id` for calls that require the user's identifier. x-displayName: Users - name: Verifications description: Identity verification (KYC) submission and status for end users. x-displayName: Verifications - name: Webhooks description: >- Register HTTPS destinations to receive event deliveries, rotate signing secrets, and inspect, update, or delete existing subscriptions. Each subscription is owned by the authenticated partner; deliveries are signed with HMAC-SHA256 and retried on transient failures. x-displayName: Webhooks paths: /v1/accounts/{account_id}/portfolio/transactions: get: tags: - Portfolio summary: List portfolio transactions description: >- Lists account portfolio transactions with optional filters for type, asset, status, transaction ID, originating reference, time range, and sort direction. Results are cursor-paginated. Results are ordered newest first by default; set `sort_direction=asc` for oldest first. Page tokens are valid for up to 24 hours. A page can contain fewer than `page_size` matching transactions, including no transactions, while still returning `next_page_token`; continue until the token is absent. Transactions can appear asynchronously. To discover new activity, poll this operation with the applicable `types` filters and an appropriate time range, omitting `statuses` or including `in_progress` while a transaction is being processed. For a transfer created by `POST /v1/transfers`, use `types=transfer` and the `from` account from the create request. For an accepted derivatives transfer created by `POST /v1/accounts/{account_id}/transfers/derivatives`, use `types=transfer` and the `account_id` from the request path. The `transfer_id` returned by either create operation is the `id` in a `reference` with `kind=transfer`. Once the transaction appears, that reference can be submitted in `references` for deterministic subsequent lookup. A transfer may appear with `status=in_progress` before it reaches the terminal `successful` or `failed` status; filtering only by `successful` can therefore hide a newly materialized transfer. The first Portfolio response after a transfer is created may contain no matching transaction even when a generic transfer has `status=complete` or a derivatives transfer has `status=accepted`; continue polling until the transaction is present. For deposits and withdrawals, `reference.kind=funding` identifies the originating funding transaction. For deposits, it is not the deposit destination or a payment reference from bank-transfer instructions; those values describe how to make the payment and are not accepted by `references`. For withdrawals, use `types=withdrawal` and, when the originating funding identifier is known, submit it in `references` as the `id` with `kind=funding`. Poll with `statuses` omitted until the withdrawal appears, then continue polling without that filter until its status is terminal: `successful` or `failed`. Filtering only by `in_progress` is useful for discovering pending withdrawals, but it excludes terminal results and must be removed or changed before polling for completion. Once a funding transaction appears, its reference can be used for deterministic subsequent lookup. The returned Portfolio transaction `id` uses the `TX` namespace and is distinct from the funding identifier in `reference.id`. operationId: listPortfolioTransactions parameters: - $ref: '#/components/parameters/PageToken' - in: query name: types schema: description: Filter by transaction type. type: array items: $ref: '#/components/schemas/Portfolio_TransactionType' style: form example: - swap - price_trigger_swap - withdrawal - transfer - $ref: '#/components/parameters/Portfolio_PageSize' - in: query name: assets schema: description: Filter transactions by specific assets. type: array items: $ref: '#/components/schemas/Portfolio_AssetFilter' style: form example: - symbol: BTC type: crypto - in: query name: start_timestamp description: Lower bound of the transaction timestamp filter. schema: $ref: '#/components/schemas/DateTime' style: form example: '2025-01-01T00:00:00Z' - in: query name: end_timestamp description: Upper bound of the transaction timestamp filter. schema: $ref: '#/components/schemas/DateTime' style: form example: '2025-12-31T23:59:59Z' - in: query name: statuses schema: description: >- Filter transactions by lifecycle status. When polling a newly created transfer or withdrawal through completion, omit this filter or provide an empty array so both `in_progress` and the terminal `successful` or `failed` status can be observed. Filtering only by `in_progress` discovers pending transactions but excludes terminal results; remove or change that filter before polling for completion. type: array items: $ref: '#/components/schemas/Portfolio_TransactionStatusFilter' style: form example: - successful - in: query name: ids schema: description: Filter transactions by specific transaction IDs. type: array items: type: string style: form example: - TX-2025-0001 - in: query name: sort_direction schema: $ref: '#/components/schemas/Portfolio_SortDirection' style: form example: desc - in: query name: quote_symbol schema: $ref: '#/components/schemas/AssetSymbol' description: >- Asset to use for quoting amounts and fees in the response. Quoting is best-effort based on rates at transaction time. If not provided or if quoting is unavailable, quoted fields will be null. style: form example: USD - in: query name: quote_type schema: $ref: '#/components/schemas/Portfolio_QuoteAssetType' description: Quote asset classification. Supports fiat and stablecoin. style: form example: fiat - in: query name: references schema: description: >- Filter by originating references. Entries are ORed together and combined with `types` and other filters using AND semantics. Reference kind selects the originating system namespace. For a deposit or withdrawal, use `kind=funding` and the originating funding identifier. For a transfer, use `kind=transfer` and the `transfer_id` returned by `POST /v1/transfers` or an accepted `POST /v1/accounts/{account_id}/transfers/derivatives` request. Reference identifiers are distinct from the `TX` identifiers accepted by `ids`. type: array items: $ref: '#/components/schemas/Portfolio_TransactionReference' style: form examples: funding-reference: summary: Originating Funding reference value: - kind: funding id: FTSBuuG-9BctU4m3Emt88submmZVKY transfer-reference: summary: Originating Transfer reference value: - kind: transfer id: TRYCMN7-WXKJM-F47YIM - $ref: '#/components/parameters/AccountId' responses: '200': description: Successful response headers: X-Trace-Id: $ref: '#/components/headers/TraceId' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: type: object properties: data: description: >- List of portfolio transactions matching the query parameters. Always present; serialized as an empty array when no transactions match. type: array items: $ref: '#/components/schemas/Portfolio_Transaction' quote_symbol: description: >- The asset used as the quote currency for all amount_in_quote fields. Present only when quote_symbol was requested. type: string quote_type: $ref: '#/components/schemas/Portfolio_QuoteAssetType' next_page_token: description: >- Opaque token for retrieving the next page. Absent when there are no more results. type: string minLength: 1 maxLength: 256 required: - data - quote_symbol - quote_type examples: first-page-btc-buy: summary: First page with a single BTC buy value: data: - id: TX-2025-0001 timestamp: '2025-09-12T14:23:11Z' type: swap status: successful details: type: swap quote_id: Q-2025-0001 spend: sub_total: symbol: USD name: US Dollar type: fiat amount: '5000.00' amount_in_quote: '5000.00' total: symbol: USD name: US Dollar type: fiat amount: '5025.00' amount_in_quote: '5025.00' timestamp: '2025-09-12T14:23:11Z' fee: symbol: USD name: US Dollar type: fiat amount: '25.00' amount_in_quote: '25.00' balance: symbol: USD name: US Dollar type: fiat amount: '4975.00' amount_in_quote: '4975.00' receive: sub_total: symbol: BTC name: Bitcoin type: crypto amount: '0.08064516' amount_in_quote: '5000.00' total: symbol: BTC name: Bitcoin type: crypto amount: '0.08064516' amount_in_quote: '5000.00' timestamp: '2025-09-12T14:23:11Z' balance: symbol: BTC name: Bitcoin type: crypto amount: '0.58064516' amount_in_quote: '35990.00' quote_symbol: USD quote_type: fiat next_page_token: MjoyRHuBXSgoe0mDHt-iFALROW46EGdvk_trgja31Vwr7H4 failed-swap: summary: Failed standard swap value: data: - id: TX-2025-0002 timestamp: '2025-09-12T14:24:11Z' type: swap status: failed details: type: failed_swap failure_reason: insufficient_funds quote_symbol: USD quote_type: fiat successful-price-trigger-swap: summary: Successful price-triggered swap value: data: - id: TX-2025-0003 timestamp: '2025-09-12T14:25:11Z' type: price_trigger_swap status: successful details: type: price_trigger_swap quote_id: Q-2025-0003 quote_symbol: USD quote_type: fiat failed-price-trigger-swap: summary: Failed price-triggered swap value: data: - id: TX-2025-0004 timestamp: '2025-09-12T14:26:11Z' type: price_trigger_swap status: failed details: type: failed_price_trigger_swap failure_reason: card_issue quote_symbol: USD quote_type: fiat received-deposit: summary: Received crypto deposit value: data: - id: TXYMPOO-MRYLI-54G4MY timestamp: '2026-07-13T10:15:30Z' type: deposit status: successful reference: kind: funding id: FTSBuuG-9BctU4m3Emt88submmZVKY details: type: funding crypto_transaction_id: '0xabc123def4567890' vout: 7 receive: sub_total: symbol: BTC name: Bitcoin type: crypto amount: '1.00' amount_in_quote: '62000.00' total: symbol: BTC name: Bitcoin type: crypto amount: '1.00' amount_in_quote: '62000.00' timestamp: '2026-07-13T10:15:30Z' quote_symbol: USD quote_type: fiat processing-fiat-deposit: summary: Fiat bank deposit still processing value: data: - id: TXFIATD-H4K2N-Q7M9PL timestamp: '2026-08-17T09:15:30Z' type: deposit status: in_progress reference: kind: funding id: FTf7QpL-4nB2xM8vK5dR9sT3wY6zA1 details: type: funding vendor_transaction_id: >- 4f3c2a1908e7d6c5b4a39281706f5e4d3c2b1a0987654321fedcba9876543210 receive: sub_total: symbol: USD type: fiat amount: '1000.00' amount_in_quote: '1000.00' fee: symbol: USD type: fiat amount: '2.50' amount_in_quote: '2.50' total: symbol: USD type: fiat amount: '997.50' amount_in_quote: '997.50' timestamp: '2026-08-17T09:15:30Z' quote_symbol: USD quote_type: fiat processing-withdrawal: summary: Crypto withdrawal awaiting settlement value: data: - id: TXWDRWL-H4K2N-Q7M9PL timestamp: '2026-08-20T09:15:30Z' type: withdrawal status: in_progress reference: kind: funding id: FTw8RkN-6pC3yM9vL2dS5tU7xZ4aB1 details: type: funding spend: sub_total: symbol: BTC type: crypto amount: '0.01000000' amount_in_quote: '620.00' fee: symbol: BTC type: crypto amount: '0.00010000' amount_in_quote: '6.20' total: symbol: BTC type: crypto amount: '0.01010000' amount_in_quote: '626.20' timestamp: '2026-08-20T09:15:30Z' quote_symbol: USD quote_type: fiat processing-fiat-withdrawal: summary: Fiat withdrawal awaiting completion value: data: - id: TXFIATW-H4K2N-Q7M9PL timestamp: '2026-09-22T09:15:30Z' type: withdrawal status: in_progress reference: kind: funding id: FTEURia-4nB2xM8vK5dR9sT3wY6zA1 details: type: funding spend: sub_total: symbol: EUR type: fiat amount: '10.00' fee: symbol: EUR type: fiat amount: '0.25' total: symbol: EUR type: fiat amount: '10.25' quote_symbol: USD quote_type: fiat created-transfer: summary: Created transfer still in progress value: data: - id: TXYCMN8-ABCD2-EFGH3I timestamp: '2026-07-23T10:15:30Z' type: transfer status: in_progress reference: kind: transfer id: TRYCMN7-WXKJM-F47YIM spend: sub_total: symbol: USD name: US Dollar type: fiat amount: '25.50' amount_in_quote: '25.50' total: symbol: USD name: US Dollar type: fiat amount: '25.50' amount_in_quote: '25.50' timestamp: '2026-07-23T10:15:30Z' receive: sub_total: symbol: USD name: US Dollar type: fiat amount: '25.50' amount_in_quote: '25.50' total: symbol: USD name: US Dollar type: fiat amount: '25.50' amount_in_quote: '25.50' timestamp: '2026-07-23T10:15:30Z' quote_symbol: USD quote_type: fiat '400': description: Validation error headers: X-Trace-Id: $ref: '#/components/headers/TraceId' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/BadRequestError' examples: invalid-request: $ref: '#/components/examples/portfolio-bad-request' invalid-reference: $ref: '#/components/examples/portfolio-invalid-reference' '401': description: Authentication required headers: X-Trace-Id: $ref: '#/components/headers/TraceId' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedError' examples: authentication-failed: $ref: '#/components/examples/portfolio-unauthenticated' '403': description: Forbidden headers: X-Trace-Id: $ref: '#/components/headers/TraceId' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' examples: caller-is-not-allowed: $ref: '#/components/examples/portfolio-forbidden' '404': description: Not found headers: X-Trace-Id: $ref: '#/components/headers/TraceId' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/NotFoundError' examples: not-found: $ref: '#/components/examples/portfolio-not-found' '429': description: Rate limit exceeded headers: X-Trace-Id: $ref: '#/components/headers/TraceId' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/ResourceExhaustedError' examples: rate-limit-exceeded: $ref: '#/components/examples/portfolio-resource-exhausted' '500': description: Internal server error headers: X-Trace-Id: $ref: '#/components/headers/TraceId' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/InternalError' examples: internal-error: $ref: '#/components/examples/portfolio-internal' '501': description: Error response headers: X-Trace-Id: $ref: '#/components/headers/TraceId' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/UnimplementedError' examples: not-implemented: $ref: '#/components/examples/portfolio-unimplemented' '503': description: Service unavailable headers: X-Trace-Id: $ref: '#/components/headers/TraceId' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/UnavailableError' examples: service-unavailable: $ref: '#/components/examples/portfolio-unavailable' '504': description: Deadline exceeded headers: X-Trace-Id: $ref: '#/components/headers/TraceId' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/DeadlineExceededError' examples: request-deadline-exceeded: $ref: '#/components/examples/portfolio-deadline-exceeded' security: - ApiKey: [] ApiSign: [] ApiNonce: [] components: parameters: PageToken: name: page_token in: query description: >- Opaque token returned as `next_page_token` in the previous response. Omit to request the first page. required: false schema: type: string minLength: 1 maxLength: 256 style: form example: MjoyRHuBXSgoe0mDHt-iFALROW46EGdvk_trgja31Vwr7H4 Portfolio_PageSize: name: page_size in: query description: >- Maximum number of results to return. Ignored when `page_token` is present. required: false schema: type: integer format: int32 minimum: 1 maximum: 25 default: 20 style: form example: 20 AccountId: name: account_id in: path required: true example: WVSD33HRMGSZUBM7 schema: $ref: '#/components/schemas/AccountId' schemas: Portfolio_TransactionType: description: >- Category of portfolio transaction. `swap` and `price_trigger_swap` represent both successful executions and failed execution attempts; use `status` to distinguish them. `deposit` and `withdrawal` represent incoming and outgoing funding transactions, respectively. `transfer` represents both transfers between accounts and movements between an account's spot and futures balances. type: string enum: - swap - price_trigger_swap - earn_reward - deposit - withdrawal - transfer - recurring_swap Portfolio_AssetFilter: description: >- Asset filter element. Pairs a symbol with its type so callers can disambiguate symbols that exist across categories (e.g., spot vs tokenized vs equity). type: object properties: symbol: $ref: '#/components/schemas/AssetSymbol' description: Asset symbol (e.g., `XBT`, `TSLAx`, `AAPL`). type: $ref: '#/components/schemas/Portfolio_AssetType' required: - symbol - type DateTime: description: RFC 3339 timestamp. type: string format: date-time Portfolio_TransactionStatusFilter: description: Lifecycle statuses available to filter transactions. type: string enum: - in_progress - successful - failed Portfolio_SortDirection: description: Sort order for transaction results by timestamp. type: string enum: - asc - desc default: desc AssetSymbol: description: Symbol identifying an asset within its asset category. type: string minLength: 1 maxLength: 16 Portfolio_QuoteAssetType: description: Quote asset classification. Supports fiat and stablecoin. type: string enum: - fiat - stablecoin default: fiat Portfolio_TransactionReference: description: >- An identifier assigned by the system from which a transaction originated. For deposits and withdrawals, `kind=funding` identifies the originating funding transaction. For a deposit, this is not a destination or a payment reference from bank-transfer instructions. For a transfer, use `kind=transfer` and the opaque `transfer_id` returned by `POST /v1/transfers` or an accepted `POST /v1/accounts/{account_id}/transfers/derivatives` request. Reference identifiers are distinct from Portfolio transaction identifiers in the `TX` namespace. type: object properties: kind: $ref: '#/components/schemas/Portfolio_TransactionReferenceKind' id: description: >- Identifier assigned by the originating system. Treat this value as opaque. type: string minLength: 1 maxLength: 128 required: - kind - id Portfolio_Transaction: description: A single portfolio transaction entry. type: object properties: id: description: >- Unique Portfolio transaction identifier in the `TX` namespace. Distinct from the identifier in `reference`. type: string timestamp: $ref: '#/components/schemas/DateTime' description: Time at which the portfolio transaction was recorded. type: $ref: '#/components/schemas/Portfolio_TransactionType' status: $ref: '#/components/schemas/Portfolio_TransactionStatus' spend: $ref: '#/components/schemas/Portfolio_TransactionSide' receive: $ref: '#/components/schemas/Portfolio_TransactionSide' reference: $ref: '#/components/schemas/Portfolio_TransactionReference' description: >- Identifier assigned by the system from which this transaction originated. Omitted when no public originating reference is available. For a deposit or withdrawal, `kind` is `funding` and `id` is the originating funding identifier. For a transfer, `kind` is `transfer` and `id` is the `transfer_id` returned by `POST /v1/transfers` or an accepted `POST /v1/accounts/{account_id}/transfers/derivatives` request. This identifier is distinct from the Portfolio transaction `id` in the `TX` namespace. details: $ref: '#/components/schemas/Portfolio_TransactionDetails' description: >- Type-specific detail for this transaction, tagged by `details.type`. Present only for transaction types with extra detail to report; omitted otherwise. New `type` values may be added over time; treat an unrecognized `details.type` as absent rather than as an error. required: - id - timestamp - type - status BadRequestError: title: Bad Request description: Request validation failed or the request could not be processed. oneOf: - title: Bad Request allOf: - $ref: '#/components/schemas/PwsValidationErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsValidationError' - type: object required: - status - code properties: status: type: integer format: int32 const: 400 code: type: string enum: - bad_request - title: Gateway description: >- Gateway-level validation failure returned before the request reaches the service. allOf: - $ref: '#/components/schemas/PwsValidationErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsValidationError' - type: object required: - status - code properties: type: type: string const: service_error status: type: integer format: int32 const: 400 code: type: string const: gateway UnauthenticatedError: title: Unauthenticated description: Authentication credentials are missing, invalid, or not accepted. oneOf: - title: Unauthenticated allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 const: 401 code: type: string enum: - unauthenticated - title: Gateway description: Authentication failure returned by the API gateway. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: type: type: string const: service_error status: type: integer format: int32 const: 401 code: type: string const: gateway ForbiddenError: title: Forbidden description: The caller is not allowed to perform this operation. oneOf: - title: Forbidden allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 const: 403 code: type: string enum: - forbidden - title: Gateway description: Authorization failure returned by the API gateway. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: type: type: string const: service_error status: type: integer format: int32 const: 403 code: type: string const: gateway NotFoundError: description: The requested resource was not found. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 const: 404 code: type: string enum: - not_found ResourceExhaustedError: description: The request was rate limited or a resource quota was exhausted. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 const: 429 code: type: string enum: - resource_exhausted InternalError: description: An unexpected server-side error occurred. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 const: 500 code: type: string enum: - internal UnimplementedError: description: The requested operation is not implemented. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 const: 501 code: type: string enum: - unimplemented UnavailableError: description: The service is temporarily unavailable. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 const: 503 code: type: string enum: - unavailable DeadlineExceededError: description: The request deadline was exceeded before a response could be produced. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 const: 504 code: type: string enum: - deadline_exceeded Portfolio_AssetType: description: Asset classification for portfolio resources. type: string enum: - fiat - crypto - xstock - stablecoin - equity Portfolio_TransactionReferenceKind: description: >- Namespace of the originating system that issued the reference. Use the kind returned with a transaction when filtering by reference. type: string enum: - funding - transfer AccountId: description: Globally unique public identifier for an account. type: string minLength: 14 maxLength: 42 Portfolio_TransactionStatus: description: >- Current processing status of a transaction. `in_progress` means the transaction is visible but not yet in a terminal state. `successful` and `failed` are terminal statuses. type: string enum: - in_progress - successful - failed Portfolio_TransactionSide: description: >- Details about one side of a transaction, either spend or receive. Values in sub_total, total, and fee are non-negative magnitudes; direction is indicated by the side on which they appear. Balance retains the signed account value. type: object properties: sub_total: $ref: '#/components/schemas/Portfolio_TransactionAmount' total: $ref: '#/components/schemas/Portfolio_TransactionAmount' timestamp: $ref: '#/components/schemas/DateTime' description: Time associated with this side of the transaction, when available. fee: $ref: '#/components/schemas/Portfolio_TransactionAmount' balance: $ref: '#/components/schemas/Portfolio_TransactionAmount' required: - sub_total - total Portfolio_TransactionDetails: description: >- Type-specific transaction detail, internally tagged by `type`. Each tag admits only the fields defined for it, so a detail belonging to one transaction type can never carry another type's fields. oneOf: - $ref: '#/components/schemas/Portfolio_FundingTransactionDetails' title: Funding transaction - $ref: '#/components/schemas/Portfolio_SwapTransactionDetails' title: Swap transaction - $ref: '#/components/schemas/Portfolio_PriceTriggerSwapTransactionDetails' title: Price-triggered swap transaction - $ref: '#/components/schemas/Portfolio_FailedSwapTransactionDetails' title: Failed swap transaction - $ref: >- #/components/schemas/Portfolio_FailedPriceTriggerSwapTransactionDetails title: Failed price-triggered swap transaction - $ref: '#/components/schemas/Portfolio_RecurringSwapTransactionDetails' title: Recurring swap transaction - $ref: '#/components/schemas/Portfolio_FailedRecurringSwapTransactionDetails' title: Failed recurring swap transaction discriminator: propertyName: type mapping: funding: '#/components/schemas/Portfolio_FundingTransactionDetails' swap: '#/components/schemas/Portfolio_SwapTransactionDetails' recurring_swap: '#/components/schemas/Portfolio_RecurringSwapTransactionDetails' price_trigger_swap: '#/components/schemas/Portfolio_PriceTriggerSwapTransactionDetails' failed_swap: '#/components/schemas/Portfolio_FailedSwapTransactionDetails' failed_recurring_swap: '#/components/schemas/Portfolio_FailedRecurringSwapTransactionDetails' failed_price_trigger_swap: >- #/components/schemas/Portfolio_FailedPriceTriggerSwapTransactionDetails PwsValidationErrorEnvelope: description: Error envelope for request validation failures. type: object required: - error properties: error: $ref: '#/components/schemas/PwsValidationError' description: Validation error details. PwsValidationError: description: Standard PWS API error object for request validation failures. type: object required: - type - status - instance - code properties: type: description: Machine-readable error class. type: string status: description: HTTP status code returned for this error. type: integer format: int32 instance: description: Request identifier for this specific error occurrence. type: string code: description: Stable machine-readable error code. type: string doc_url: description: Optional link to documentation for this error. type: string format: uri causes: description: Validation failures that contributed to the error. type: array items: $ref: '#/components/schemas/PwsErrorCause' PwsGeneralErrorEnvelope: description: Error envelope for operational or domain failures. type: object required: - error properties: error: $ref: '#/components/schemas/PwsGeneralError' description: General error details. PwsGeneralError: description: Standard PWS API error object for non-validation failures. allOf: - $ref: '#/components/schemas/PwsErrorBase' - type: object properties: causes: description: Additional error details, when present. type: array items: type: object additionalProperties: true Portfolio_TransactionAmount: description: Amount of an asset involved in a transaction. type: object properties: symbol: description: Asset symbol (e.g., "BTC", "USD", "TSLAx"). type: string amount: description: Amount in the asset's native units. type: string name: description: Human-readable name of the asset (e.g., "Bitcoin"). type: string type: $ref: '#/components/schemas/Portfolio_AssetType' amount_in_quote: description: >- Value of amount converted to the requested quote currency, if available. type: string required: - symbol - amount - type Portfolio_FundingTransactionDetails: description: >- Detail for `deposit` and `withdrawal` transactions, which settle through funding. type: object properties: type: description: Discriminator identifying this as funding detail. type: string enum: - funding crypto_transaction_id: description: >- On-chain transaction id or hash for this funding movement, when available. For withdrawals, the hash can remain absent after broadcast or block inclusion until completion is reported. Omitted for fiat funding. Treat this value as opaque; its format varies by network. type: string vout: description: >- Output index identifying the credited output within an on-chain transaction. type: integer format: int64 minimum: 0 vendor_transaction_id: description: >- Provider-assigned reference used to correlate the funding transaction. For Lightning deposits, this is the payment hash. Treat this value as opaque. type: string minLength: 1 required: - type Portfolio_SwapTransactionDetails: description: Detail for a successful `swap` transaction. type: object properties: type: description: Discriminator identifying this as standard swap detail. type: string enum: - swap quote_id: description: Identifier of the quote that executed this swap. type: string required: - type - quote_id Portfolio_PriceTriggerSwapTransactionDetails: description: Detail for a successful `price_trigger_swap` transaction. type: object properties: type: description: Discriminator identifying this as price-triggered swap detail. type: string enum: - price_trigger_swap quote_id: description: Identifier of the quote that executed this swap. type: string required: - type - quote_id Portfolio_FailedSwapTransactionDetails: description: Detail for a failed `swap` transaction. type: object properties: type: description: Discriminator identifying this as failed standard swap detail. type: string enum: - failed_swap failure_reason: $ref: '#/components/schemas/Portfolio_SwapFailureReason' description: Reason the swap failed. required: - type - failure_reason Portfolio_FailedPriceTriggerSwapTransactionDetails: description: Detail for a failed `price_trigger_swap` transaction. type: object properties: type: description: >- Discriminator identifying this as failed price-triggered swap detail. type: string enum: - failed_price_trigger_swap failure_reason: $ref: '#/components/schemas/Portfolio_SwapFailureReason' description: Reason the swap failed. required: - type - failure_reason Portfolio_RecurringSwapTransactionDetails: description: Detail for a successful `recurring_swap` execution. type: object properties: type: description: Discriminator identifying this as recurring swap detail. type: string enum: - recurring_swap quote_id: description: Identifier of the quote that executed this recurring swap. type: string required: - type - quote_id Portfolio_FailedRecurringSwapTransactionDetails: description: Detail for a failed `recurring_swap` execution. type: object properties: type: description: Discriminator identifying this as failed recurring swap detail. type: string enum: - failed_recurring_swap failure_reason: $ref: '#/components/schemas/Portfolio_SwapFailureReason' description: Reason the recurring swap execution failed. required: - type - failure_reason PwsErrorCause: description: A single request validation failure. type: object required: - field - message properties: field: description: Dot-notation path to the offending request field. type: string message: description: Human-readable explanation of the failed validation rule. type: string PwsErrorBase: description: Common fields present on every PWS API error object. type: object required: - type - status - instance - code properties: type: description: Machine-readable error class. type: string status: description: HTTP status code returned for this error. type: integer format: int32 instance: description: Request identifier for this specific error occurrence. type: string code: description: Stable machine-readable error code. type: string doc_url: description: Optional link to documentation for this error. type: string format: uri Portfolio_SwapFailureReason: description: Public category for why a swap transaction failed. type: string enum: - insufficient_funds - card_issue - user_account_issue - other headers: TraceId: description: Trace identifier for the request. Include it when contacting support. schema: type: string example: 4bf92f3577b34da6a3ce929d0e0e4736 StrictTransportSecurity: description: Enforces HTTPS for the duration specified by `max-age`. schema: type: string example: max-age=31536000; includeSubDomains; preload CacheControl: description: Prevents caching of sensitive financial data. Always `no-store`. schema: type: string enum: - no-store example: no-store examples: portfolio-bad-request: summary: Invalid request value: error: type: portfolio_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b status: 400 code: bad_request causes: - field: account_id message: must be a valid account identifier portfolio-invalid-reference: summary: Invalid transaction reference value: error: type: portfolio_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b status: 400 code: bad_request causes: - field: references[0].id message: Must be a valid reference identifier for the selected kind portfolio-unauthenticated: summary: Authentication failed value: error: type: portfolio_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b status: 401 code: unauthenticated portfolio-forbidden: summary: Caller is not allowed value: error: type: portfolio_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b status: 403 code: forbidden portfolio-not-found: summary: Resource not found value: error: type: portfolio_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b status: 404 code: not_found portfolio-resource-exhausted: summary: Rate limit exceeded value: error: type: portfolio_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b status: 429 code: resource_exhausted portfolio-internal: summary: Internal server error value: error: type: portfolio_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b status: 500 code: internal portfolio-unimplemented: summary: Operation is not implemented value: error: type: portfolio_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b status: 501 code: unimplemented portfolio-unavailable: summary: Service unavailable value: error: type: portfolio_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b status: 503 code: unavailable portfolio-deadline-exceeded: summary: Request deadline exceeded value: error: type: portfolio_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b status: 504 code: deadline_exceeded securitySchemes: ApiKey: type: apiKey in: header name: API-Key description: Your public API key. Identifies the partner making the request. ApiSign: type: apiKey in: header name: API-Sign description: HMAC signature over the request, computed with your private key. ApiNonce: type: apiKey in: header name: API-Nonce description: Monotonically increasing nonce included in the request signature. ````