> ## 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. # Get price trigger swap > Returns the current state of a single price trigger swap by ID. Use this to poll a swap's `status` after creation, after a webhook delivery, or to inspect the trigger and action that were configured. The response includes the swap's `cancelled_reason` when `status` is `cancelled`. ## OpenAPI ````yaml /api-reference/openapi_v3_pws.json get /v1/accounts/{account_id}/price-trigger-swaps/{price_trigger_swap_id} openapi: 3.1.0 info: title: Payward Services API description: >- The Payward Services (PWS) public API. PWS exposes Swaps (institutional FX-style trading), Conversions (rule-driven and one-shot fiat ↔ crypto value movement), retail-style Quotes and Price Trigger Swaps, end-user Users / Verifications, Funds (deposits, withdrawals, addresses, transactions), Portfolio, Earn, Reports, Webhooks, and Ramp (hosted fiat-to-crypto on-ramp checkout). All requests must be authenticated. All monetary values are decimal strings; all timestamps are ISO 8601 UTC. List endpoints are cursor-paginated. Errors follow a uniform shape (see `*ErrorResponse` schemas). version: v1 contact: name: Payward Services API Support url: https://docs.payward.com email: api-support@payward.com servers: - url: https://api.services.payward.com description: Production security: - ApiKey: [] ApiNonce: [] ApiSign: [] tags: - name: Users description: >- Users and headless-user onboarding flows that the partner manages. - **Create User** provisions a user with full identity verification fields collected up front. - **Create Headless User** provisions a lightweight user when your licensing agreement allows you to manage KYC data outside Payward. - **Get User** retrieves the user's profile, verification status, and required actions. - **Update User** updates user profile fields and may re-trigger verification. Use the returned user `id` for calls that require the user's identifier. - name: Assets description: >- Catalog of assets available on the platform with retail-display metadata (logos, market data, descriptions). - name: Conversions description: >- Rule-driven and one-shot fiat ↔ crypto value movement, including conversion rules, deposits, and whitelisted wallets. - name: Earn description: >- Manage auto-earn preferences and retrieve allocation and reward information. - name: Funds description: >- Deposits, withdrawals, addresses, methods, and the consolidated funding-transactions ledger. - name: Portfolio description: End-user portfolio summary, history, and transaction views. - name: Price Trigger Swaps description: Limit-style orders that execute when a configured price trigger is met. - name: On-chain Swaps description: >- Wallet-funded onchain quote trading for xStock and USDC pairs. On-chain quotes settle on-chain through the Payward on-chain proxy contract. - name: Ramp description: >- Hosted fiat-to-crypto on-ramp checkout: country / fiat / payment-method / cryptocurrency-asset discovery, transaction limits and prospective quotes, and the hosted checkout URL. - name: Reports description: Settlement and reconciliation reports for the partner. - name: Swaps description: >- Direct partner-to-Payward swap quotes and executions (institutional FX-style trading). - name: Verifications description: Identity verification (KYC) submission and status for end users. - name: Webhooks description: Manage webhook subscriptions for asynchronous event delivery. paths: /v1/accounts/{account_id}/price-trigger-swaps/{price_trigger_swap_id}: get: tags: - Price Trigger Swaps summary: Get price trigger swap description: >- Returns the current state of a single price trigger swap by ID. Use this to poll a swap's `status` after creation, after a webhook delivery, or to inspect the trigger and action that were configured. The response includes the swap's `cancelled_reason` when `status` is `cancelled`. operationId: getPriceTriggerSwap parameters: - $ref: '#/components/parameters/AccountIdPath' - in: path name: price_trigger_swap_id required: true schema: description: ID of the price trigger swap to retrieve (prefixed with `swap_`). type: string style: simple responses: '200': description: Successful response content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/PriceTriggerSwap' examples: active-swap: summary: Swap in `active` status awaiting trigger evaluation value: data: id: swap_01J0M7C0Z9F8YX3GQH8E external_reference: buy-dip-btc-001 trade: from: symbol: USD name: US Dollar type: fiat amount: '100.00' to: symbol: BTC name: Bitcoin type: crypto when: base: symbol: BTC name: Bitcoin type: crypto quote: symbol: USD name: US Dollar type: fiat drops_to: '50000.00' status: active completed-swap: summary: >- Swap completed after a successful trade execution; `trade.fees` and `trade.rate` reflect what was realized value: data: id: swap_01J0M7BMRWJTKBN0R0FY external_reference: buy-dip-btc-001 trade: from: symbol: USD name: US Dollar type: fiat amount: '100.00' to: symbol: BTC name: Bitcoin type: crypto fees: trade: symbol: USD name: US Dollar type: fiat amount: '0.50' rate: base: symbol: BTC name: Bitcoin type: crypto quote: symbol: USD name: US Dollar type: fiat price: '50000.00' when: base: symbol: BTC name: Bitcoin type: crypto quote: symbol: USD name: US Dollar type: fiat drops_to: '50000.00' status: completed headers: Request-Id: $ref: '#/components/headers/RequestId' X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' X-Content-Type-Options: $ref: '#/components/headers/XContentTypeOptions' Content-Security-Policy: $ref: '#/components/headers/ContentSecurityPolicy' Cache-Control: $ref: '#/components/headers/CacheControl' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ValidationErrorResponse' headers: Request-Id: $ref: '#/components/headers/RequestId' X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' X-Content-Type-Options: $ref: '#/components/headers/XContentTypeOptions' Content-Security-Policy: $ref: '#/components/headers/ContentSecurityPolicy' Cache-Control: $ref: '#/components/headers/CacheControl' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedErrorResponse' headers: Request-Id: $ref: '#/components/headers/RequestId' X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' X-Content-Type-Options: $ref: '#/components/headers/XContentTypeOptions' Content-Security-Policy: $ref: '#/components/headers/ContentSecurityPolicy' Cache-Control: $ref: '#/components/headers/CacheControl' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ForbiddenErrorResponse' headers: Request-Id: $ref: '#/components/headers/RequestId' X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' X-Content-Type-Options: $ref: '#/components/headers/XContentTypeOptions' Content-Security-Policy: $ref: '#/components/headers/ContentSecurityPolicy' Cache-Control: $ref: '#/components/headers/CacheControl' '404': description: Price trigger swap not found content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' headers: Request-Id: $ref: '#/components/headers/RequestId' X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' X-Content-Type-Options: $ref: '#/components/headers/XContentTypeOptions' Content-Security-Policy: $ref: '#/components/headers/ContentSecurityPolicy' Cache-Control: $ref: '#/components/headers/CacheControl' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/RateLimitErrorResponse' headers: Request-Id: $ref: '#/components/headers/RequestId' X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' X-Content-Type-Options: $ref: '#/components/headers/XContentTypeOptions' Content-Security-Policy: $ref: '#/components/headers/ContentSecurityPolicy' Cache-Control: $ref: '#/components/headers/CacheControl' Retry-After: $ref: '#/components/headers/RetryAfter' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/InternalErrorResponse' headers: Request-Id: $ref: '#/components/headers/RequestId' X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' X-Content-Type-Options: $ref: '#/components/headers/XContentTypeOptions' Content-Security-Policy: $ref: '#/components/headers/ContentSecurityPolicy' Cache-Control: $ref: '#/components/headers/CacheControl' '503': description: Service unavailable content: application/json: schema: $ref: '#/components/schemas/ServiceUnavailableErrorResponse' headers: Request-Id: $ref: '#/components/headers/RequestId' X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' X-Content-Type-Options: $ref: '#/components/headers/XContentTypeOptions' Content-Security-Policy: $ref: '#/components/headers/ContentSecurityPolicy' Cache-Control: $ref: '#/components/headers/CacheControl' '504': description: Deadline exceeded content: application/json: schema: $ref: '#/components/schemas/DeadlineExceededErrorResponse' headers: Request-Id: $ref: '#/components/headers/RequestId' X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' X-Content-Type-Options: $ref: '#/components/headers/XContentTypeOptions' Content-Security-Policy: $ref: '#/components/headers/ContentSecurityPolicy' Cache-Control: $ref: '#/components/headers/CacheControl' security: - ApiKey: [] ApiNonce: [] ApiSign: [] x-codeSamples: - lang: bash label: curl source: >- curl -X GET "https://api.services.payward.com/v1/accounts/W4BE9868GY65TB6523/price-trigger-swaps/swap_01J0M7C0Z9F8YX3GQH8E" \ -H "API-Key: $PWS_API_KEY" \ -H "API-Nonce: $PWS_API_NONCE" \ -H "API-Sign: $PWS_API_SIGN" components: parameters: AccountIdPath: in: path name: account_id required: true description: >- ID of the account the request applies to. This refers to one of the accounts held by the user the request is acting on behalf of (typically the user's main account, but any of the user's accounts is accepted). Routes the request to that specific account container. schema: $ref: '#/components/schemas/AccountId' example: W4BE9868GY65TB6523 schemas: PriceTriggerSwap: description: >- A price trigger swap that submits a trade when its `when` condition is met. type: object properties: id: description: Unique identifier for this price trigger swap. type: string example: AGHJB4-MMBOW-KANZXS status: $ref: '#/components/schemas/PriceTriggerSwapStatus' requested: description: Trade and trigger condition requested by the client. allOf: - $ref: '#/components/schemas/PriceTriggerSwapRequested' executed: description: Realized trade details. Present once `status` is `completed`. allOf: - $ref: '#/components/schemas/PriceTriggerSwapExecuted' failure_reason: description: Why the swap failed. Present only when `status` is `failed`. allOf: - $ref: '#/components/schemas/PriceTriggerSwapFailureReason' created_at: description: Time at which the price trigger swap was created. allOf: - $ref: '#/components/schemas/DateTime' updated_at: description: Time at which the price trigger swap was last updated. allOf: - $ref: '#/components/schemas/DateTime' required: - id - status - requested - created_at - updated_at ValidationErrorResponse: description: The request was rejected because the client supplied invalid input. type: object properties: error: description: Error details. type: object properties: type: type: string status: type: integer format: int32 enum: - 400 instance: type: string code: type: string enum: - bad_request doc_url: type: string format: uri causes: type: array items: $ref: '#/components/schemas/ValidationCause' required: - type - status - instance - code required: - error UnauthenticatedErrorResponse: description: Authentication credentials were missing or invalid. type: object properties: error: description: Error details. type: object properties: type: type: string status: type: integer format: int32 enum: - 401 instance: type: string code: type: string enum: - unauthenticated doc_url: type: string format: uri causes: type: array items: type: object additionalProperties: true required: - type - status - instance - code required: - error ForbiddenErrorResponse: description: The caller is authenticated but is not allowed to perform this action. type: object properties: error: description: Error details. type: object properties: type: type: string status: type: integer format: int32 enum: - 403 instance: type: string code: type: string enum: - forbidden doc_url: type: string format: uri causes: type: array items: type: object additionalProperties: true required: - type - status - instance - code required: - error NotFoundErrorResponse: description: The requested resource does not exist. type: object properties: error: description: Error details. type: object properties: type: type: string enum: - request_error status: type: integer format: uint16 enum: - 404 instance: type: string code: type: string enum: - not_found doc_url: type: - string - 'null' format: uri required: - type - status - instance - code required: - error RateLimitErrorResponse: description: The request rate limit was exceeded. type: object properties: error: description: Error details. type: object properties: type: type: string status: type: integer format: int32 enum: - 429 instance: type: string code: type: string enum: - resource_exhausted doc_url: type: string format: uri causes: type: array items: type: object additionalProperties: true required: - type - status - instance - code required: - error InternalErrorResponse: description: An internal server error occurred. type: object properties: error: description: Error details. type: object properties: type: type: string status: type: integer format: int32 enum: - 500 instance: type: string code: type: string enum: - internal doc_url: type: string format: uri causes: type: array items: type: object additionalProperties: true required: - type - status - instance - code required: - error ServiceUnavailableErrorResponse: description: The service is temporarily unavailable. type: object properties: error: description: Error details. type: object properties: type: type: string status: type: integer format: int32 enum: - 503 instance: type: string code: type: string enum: - unavailable doc_url: type: string format: uri causes: type: array items: type: object additionalProperties: true required: - type - status - instance - code required: - error DeadlineExceededErrorResponse: description: The upstream request deadline was exceeded. type: object properties: error: description: Error details. type: object properties: type: type: string status: type: integer format: int32 enum: - 504 instance: type: string code: type: string enum: - deadline_exceeded doc_url: type: string format: uri causes: type: array items: type: object additionalProperties: true required: - type - status - instance - code required: - error AccountId: type: string description: Canonical identifier for an account in the Payward public API. minLength: 14 maxLength: 42 PriceTriggerSwapStatus: description: >- Current lifecycle status of a price trigger swap. - `active`: awaiting trigger evaluation. - `completed`: the trigger fired and the trade executed successfully. Terminal. Realized details are available on `executed`. - `cancelled`: the order was cancelled before completion. Terminal. - `failed`: the trigger fired but the trade could not be completed. Terminal. See `failure_reason`. type: string enum: - active - completed - cancelled - failed PriceTriggerSwapRequested: description: >- Trade and trigger condition requested by the client when the swap was created. type: object properties: trade: description: Trade to execute when the condition fires. allOf: - $ref: '#/components/schemas/PriceTriggerSwapRequestedTrade' when: description: Price condition that triggers the trade. allOf: - $ref: '#/components/schemas/PriceTriggerSwapConditionResponse' required: - trade - when PriceTriggerSwapExecuted: description: >- Realized trade details for an executed price trigger swap. Present once `status` is `completed`. type: object properties: from: description: Source asset and amount executed. allOf: - $ref: '#/components/schemas/AssetAmountResponse' to: description: Destination asset and amount received. allOf: - $ref: '#/components/schemas/AssetAmountResponse' rate: description: Exchange rate at which the trade executed. allOf: - $ref: '#/components/schemas/Rate' fees: description: Fees charged on the executed trade. allOf: - $ref: '#/components/schemas/Fees' executed_at: description: Time at which the trade executed. allOf: - $ref: '#/components/schemas/DateTime' required: - from - to - rate - fees - executed_at PriceTriggerSwapFailureReason: description: >- Reason a price trigger swap failed. Present only when `status` is `failed`. type: string enum: - user_locked - expired_payment_method - asset_unavailable - pair_unavailable - retries_exhausted - funding_method_deleted - other DateTime: type: string format: date-time description: A RFC 3339 datetime example: '2023-03-13T12:34:56Z' ValidationCause: description: One failed field-level validation rule. type: object 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 required: - field - message PriceTriggerSwapRequestedTrade: description: >- Requested trade attached to a price trigger swap. Exactly one of `from`/`to` carries `amount`; the other side is filled when the trade executes. type: object properties: from: description: Requested source asset and optional fixed amount. allOf: - $ref: '#/components/schemas/AssetAmountResponse' to: description: Requested destination asset and optional fixed amount. allOf: - $ref: '#/components/schemas/AssetAmountResponse' fee: description: Partner fee applied to the trade. allOf: - $ref: '#/components/schemas/PartnerFee' required: - from - to - fee PriceTriggerSwapConditionResponse: description: >- The condition under which the order's `trade` fires. Watches the price of the `base`/`quote` asset pair and fires when the live price reaches the threshold. Specify exactly one of `drops_to` or `rises_to`: - `drops_to`: fires when the price falls to or below the value (e.g. "buy on dip"). - `rises_to`: fires when the price rises to or above the value (e.g. "take profit"). type: object properties: base: description: Base asset of the pair to monitor. allOf: - $ref: '#/components/schemas/AssetRefResponse' quote: description: Quote asset of the pair to monitor. allOf: - $ref: '#/components/schemas/AssetRefResponse' drops_to: description: >- Fire when the price reaches this value or below. Decimal string. Mutually exclusive with `rises_to`. type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 example: '50000.00' rises_to: description: >- Fire when the price reaches this value or above. Decimal string. Mutually exclusive with `drops_to`. type: string pattern: ^-?[0-9]+(\.[0-9]+)?$ minLength: 1 maxLength: 64 example: '80000.00' required: - base - quote oneOf: - type: object required: - drops_to not: required: - rises_to - type: object required: - rises_to not: required: - drops_to AssetAmountResponse: description: >- An asset and an amount denominated in that asset, as returned in responses. Includes the human-readable asset `name`. type: object properties: symbol: description: Asset ticker symbol (e.g. "BTC", "USD", "TSLAx"). type: string name: description: >- Human-readable name of the asset (e.g. "Bitcoin" for BTC). Populated by the server in responses. type: - string - 'null' type: description: Classification of the asset. type: string enum: - fiat - crypto - stablecoin - xstock amount: description: Decimal amount as a string to preserve precision. type: string format: decimal128 required: - symbol - type Rate: description: Exchange rate applied to a quote. type: object properties: base: description: Base asset of the rate pair. allOf: - $ref: '#/components/schemas/AssetRefResponse' quote: description: Quote asset of the rate pair. allOf: - $ref: '#/components/schemas/AssetRefResponse' price: description: Price of one unit of the base asset denominated in the quote asset. type: string format: decimal128 required: - base - quote - price Fees: description: Breakdown of all fees charged for a quote. type: object properties: trade: $ref: '#/components/schemas/Fee' PartnerFee: description: >- Partner-configured fee applied on top of the underlying execution price. Request-only — never returned in response payloads. type: object properties: bps: description: Fee in basis points (1 bps = 0.01%). type: integer minimum: 0 maximum: 10000 example: 50 required: - bps AssetRefResponse: description: >- Reference to an asset by its ticker symbol and classification, as returned in responses. Includes the human-readable asset `name`. type: object properties: symbol: description: Asset ticker symbol (e.g. "BTC", "USD", "TSLAx"). type: string name: description: >- Human-readable name of the asset (e.g. "Bitcoin" for BTC). Populated by the server in responses. type: - string - 'null' type: description: Classification of the asset. type: string enum: - fiat - crypto - stablecoin - equity - xstock required: - symbol - type Fee: description: A single fee charged against a quote. type: object properties: symbol: description: Asset ticker the fee is denominated in (e.g. "USD"). type: string name: description: >- Human-readable name of the asset (e.g. "Bitcoin" for BTC). Populated by the server in responses. type: - string - 'null' type: description: Classification of the fee asset. type: string enum: - fiat - crypto - stablecoin - xstock amount: description: Fee amount as a decimal string. type: string format: decimal128 required: - symbol - type - amount headers: RequestId: description: >- Unique identifier for tracing this request across services. Include in support tickets. schema: type: string format: uuid example: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b RateLimitLimit: description: Total requests allowed in the current window. schema: type: integer example: 1000 RateLimitRemaining: description: Requests remaining in the current window. schema: type: integer example: 955 RateLimitReset: description: Unix timestamp (seconds) when the rate-limit window resets. schema: type: integer format: int64 example: 1713182400 StrictTransportSecurity: description: >- Enforces HTTPS for the configured period. Always `max-age=63072000; includeSubDomains; preload`. schema: type: string example: max-age=63072000; includeSubDomains; preload XContentTypeOptions: description: Disables MIME sniffing. Always `nosniff`. schema: type: string enum: - nosniff example: nosniff ContentSecurityPolicy: description: >- Prevents embedding and resource loading. Always `default-src 'none'; frame-ancestors 'none'`. schema: type: string example: default-src 'none'; frame-ancestors 'none' CacheControl: description: Prevents caching of sensitive financial data. Always `no-store`. schema: type: string enum: - no-store example: no-store RetryAfter: description: Seconds the client should wait before retrying. schema: type: integer example: 30 securitySchemes: ApiKey: type: apiKey name: API-Key in: header description: Your public API key. Identifies the partner making the request. ApiNonce: type: apiKey name: API-Nonce in: header description: Monotonically increasing nonce included in the request signature. ApiSign: type: apiKey name: API-Sign in: header description: HMAC signature over the request, computed with your private key. ````