> ## 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 on-demand conversion > Returns an on-demand conversion and its current status. ## OpenAPI ````yaml /api-reference/openapi_v3_pws.json get /v1/accounts/{account_id}/on-demand-conversions/{conversion_id} openapi: 3.1.0 info: title: Payward Services API description: >- The Payward Services (PWS) public API. PWS exposes Swaps (institutional FX-style trading), Conversion rules (rule-driven fiat ↔ crypto value movement), retail-style Quotes and Price Trigger Swaps, end-user Users / Verifications, Travel Rule address ownership verification, 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: [] ApiSign: [] ApiNonce: [] tags: - name: Users description: >- User onboarding and status flows that the partner manages. - **Create User** provisions a user with an email and external reference. - **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. - name: Assets description: >- Catalog of assets available on the platform with retail-display metadata (logos, market data, descriptions). - name: Conversion rules x-group: Users description: >- Rule-driven fiat ↔ crypto value movement, including conversion rules and deposits. - name: On-demand conversions x-group: Users description: One-off conversions from an account balance to a wallet destination. - 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: Bank Links description: >- Link US bank accounts to an account through a Kraken-hosted widget, then reference them for money movement. Two resources model a connection: - A **Bank Link** is the connection between one account and one banking institution. Create it to get a hosted-widget URL, and send the user there to choose their institution and approve access. One account can hold many Bank Links. - An **Account Link** is one bank account — a checking account, for example — that the user shared through that connection. One Bank Link owns one or more Account Links. Use `account_link_id` to reference the bank account when you move money. Both ids are opaque handles. Provider identifiers, access tokens, owner names, and raw bank numbers are never exposed. Eligibility is evaluated on every read, and ownership must match: the bank account's holder must match the account's verified holder. An account that fails ownership validation reports `ineligible` with the reason `name_mismatch`. Unlinking is permanent. Linking the same bank account again creates a new Bank Link and a new `account_link_id`; old ids stay valid only for reading history. - 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: Travel Rule Verifications description: Travel Rule address ownership verification flows. - 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}/on-demand-conversions/{conversion_id}: get: tags: - On-demand conversions summary: Get on-demand conversion description: Returns an on-demand conversion and its current status. operationId: getOnDemandConversion parameters: - in: path name: account_id required: true schema: description: Identifier of the selected account that owns the conversion. type: string minLength: 14 maxLength: 42 example: WVSD33HRMGSZUBM7 example: WVSD33HRMGSZUBM7 - in: path name: conversion_id required: true schema: description: On-demand conversion identifier. type: string format: uuid style: simple example: 00000000-0000-0000-0000-000000000001 responses: '200': description: On-demand conversion returned. content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/OnDemandConversion' examples: id-get-on-demand-conversion-ok: summary: GetOnDemandConversion returns an on-demand conversion value: data: id: 00000000-0000-0000-0000-000000000001 status: completed from: symbol: USD amount: '100.00' type: balance status: settled to: symbol: BTC amount: '0.00150' type: wallet status: settled wallet: via: bitcoin address: bc1qexamplewallet002 memo: destination-memo tag: destination-tag rate: base: symbol: USD quote: symbol: BTC price: '0.00001520' fees: to: symbol: BTC amount: '0.00001' transaction_references: to: transaction_id: withdrawal-1 blockchain_transaction_id: chain-1 created_at: '2026-08-12T12:55:00Z' updated_at: '2026-08-12T13:02:03Z' '400': description: Validation error. content: application/json: schema: $ref: '#/components/schemas/BadRequestError' '401': description: Authentication required. content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedError' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' '404': description: On-demand conversions are not activated. content: application/json: schema: $ref: '#/components/schemas/ConversionsNotFoundErrorResponse' '429': description: Rate limit exceeded. content: application/json: schema: $ref: '#/components/schemas/ResourceExhaustedError' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/InternalError' '503': description: Service unavailable. content: application/json: schema: $ref: '#/components/schemas/UnavailableError' '504': description: Deadline exceeded. content: application/json: schema: $ref: '#/components/schemas/DeadlineExceededError' security: - ApiKey: [] ApiSign: [] ApiNonce: [] components: schemas: OnDemandConversion: description: >- Details of an on-demand conversion. It includes the amount debited from the account, the amount delivered to the wallet, the exchange rate, destination details, and timestamps. Fees and transaction references are included when available. A saved destination memo or tag is returned in every response. type: object required: - id - status - from - to - rate - created_at - updated_at properties: id: description: Unique identifier for this on-demand conversion. type: string format: uuid status: $ref: '#/components/schemas/OnDemandConversionStatus' from: $ref: '#/components/schemas/OnDemandConversionEndpoint' to: $ref: '#/components/schemas/OnDemandConversionEndpoint' rate: $ref: '#/components/schemas/OnDemandConversionRate' fees: $ref: '#/components/schemas/OnDemandConversionFees' transaction_references: $ref: '#/components/schemas/OnDemandConversionTransactionReferences' created_at: $ref: '#/components/schemas/google.protobuf.Timestamp' updated_at: $ref: '#/components/schemas/google.protobuf.Timestamp' BadRequestError: description: Request validation failed or the request could not be processed. 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 enum: - 400 code: type: string enum: - bad_request UnauthenticatedError: description: Authentication credentials are missing, invalid, or not accepted. 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 enum: - 401 code: type: string enum: - unauthenticated ForbiddenError: 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 enum: - 403 code: type: string enum: - forbidden - $ref: '#/components/schemas/GatewayError' ConversionsNotFoundErrorResponse: description: The requested resource does not exist. 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 enum: - 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 enum: - 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 enum: - 500 code: type: string enum: - internal 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 enum: - 503 code: type: string enum: - unavailable DeadlineExceededError: description: The upstream service did not complete the request before the deadline. 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 enum: - 504 code: type: string enum: - deadline_exceeded OnDemandConversionStatus: description: >- Current lifecycle status of an on-demand conversion. `converting` means the conversion is in progress. `settling` means the converted asset is being delivered to the destination. `completed` means the conversion finished successfully. `failed` means the conversion could not be completed. type: string enum: - converting - settling - failed - completed OnDemandConversionEndpoint: description: Amount and details returned for one side of an on-demand conversion. discriminator: propertyName: type mapping: balance: $ref: '#/components/schemas/OnDemandConversionBalanceEndpoint' wallet: $ref: '#/components/schemas/OnDemandConversionWalletEndpoint' oneOf: - $ref: '#/components/schemas/OnDemandConversionBalanceEndpoint' title: OnDemandConversionBalanceEndpoint - $ref: '#/components/schemas/OnDemandConversionWalletEndpoint' title: OnDemandConversionWalletEndpoint OnDemandConversionRate: description: Exchange rate applied to an on-demand conversion. type: object required: - base - quote - price properties: base: $ref: '#/components/schemas/OnDemandConversionRateAsset' description: Base asset of the rate pair. quote: $ref: '#/components/schemas/OnDemandConversionRateAsset' description: Quote asset of the rate pair. price: description: Price of one unit of the base asset denominated in the quote asset. type: string OnDemandConversionFees: description: >- Breakdown of all fees charged for an on-demand conversion, when available. type: object additionalProperties: false properties: to: $ref: '#/components/schemas/OnDemandConversionFee' description: >- Fees charged on the destination side of the conversion, when available. OnDemandConversionTransactionReferences: description: Transaction references produced by the conversion, when available. type: object additionalProperties: false properties: to: $ref: '#/components/schemas/OnDemandConversionTransactionReference' description: >- Transaction reference for the destination side of the conversion, when available. google.protobuf.Timestamp: description: RFC 3339 timestamp. type: string format: date-time 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 GatewayError: title: Gateway type: object required: - error properties: error: type: object required: - type - status - code properties: type: type: string const: service_error status: type: integer format: int32 const: 403 code: type: string const: gateway OnDemandConversionBalanceEndpoint: description: >- Balance source side of an on-demand conversion and its current settlement status. type: object additionalProperties: false required: - symbol - type - amount - status properties: symbol: description: Asset symbol for this conversion side. type: string minLength: 1 maxLength: 16 type: title: OnDemandConversionBalanceEndpointType description: Type of source side. Always `balance`. type: string enum: - balance amount: description: Amount debited from the selected account balance. type: string minLength: 1 maxLength: 64 status: title: OnDemandConversionSettlementStatus description: Current settlement status of this conversion side. type: string enum: - pending - held - settled - failed OnDemandConversionWalletEndpoint: description: >- Wallet destination side of an on-demand conversion and its current settlement status. type: object additionalProperties: false required: - symbol - type - wallet - amount - status properties: symbol: description: Asset symbol for this conversion side. type: string minLength: 1 maxLength: 16 type: title: OnDemandConversionWalletEndpointType description: Type of destination side. Always `wallet`. type: string enum: - wallet wallet: $ref: '#/components/schemas/OnDemandConversionWalletTarget' amount: description: Amount delivered to the destination wallet. type: string minLength: 1 maxLength: 64 status: title: OnDemandConversionSettlementStatus description: Current settlement status of this conversion side. type: string enum: - pending - held - settled - failed OnDemandConversionRateAsset: description: Asset in an on-demand conversion rate pair. type: object required: - symbol properties: symbol: description: Asset ticker symbol for the rate pair. type: string OnDemandConversionFee: description: A single fee charged for an on-demand conversion. type: object additionalProperties: false required: - symbol - amount properties: symbol: description: Asset ticker symbol the fee is denominated in. type: string minLength: 1 maxLength: 16 amount: description: Fee amount as a decimal string. type: string minLength: 1 maxLength: 64 OnDemandConversionTransactionReference: description: Transaction references for one conversion leg. type: object additionalProperties: false properties: transaction_id: description: Internal transaction identifier. type: string minLength: 1 maxLength: 256 blockchain_transaction_id: description: Blockchain transaction identifier, when available. type: string minLength: 1 maxLength: 256 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 OnDemandConversionWalletTarget: description: Destination wallet details for an on-demand conversion. type: object additionalProperties: false required: - via - address properties: via: description: Network used to deliver the asset to the wallet. type: string minLength: 1 maxLength: 32 address: description: Destination wallet address on the selected network. type: string minLength: 1 maxLength: 256 memo: description: Optional memo required by some destination networks. type: string minLength: 1 maxLength: 64 tag: description: Optional tag required by some destination networks. type: string minLength: 1 maxLength: 64 securitySchemes: ApiKey: type: apiKey name: API-Key in: header description: Your public API key. Identifies the partner making the request. ApiSign: type: apiKey name: API-Sign in: header description: HMAC signature over the request, computed with your private key. ApiNonce: type: apiKey name: API-Nonce in: header description: Monotonically increasing nonce included in the request signature. ````