> ## 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. # Create withdrawal > Creates a cryptocurrency withdrawal from the selected account to a registered funding address. Optionally supply `fee_token` from [Calculate funding fees](/api-reference/funds/calculate-funding-fees) to reuse a quote's fee terms. To safely retry a request with an unknown outcome, supply a UUIDv4 `Idempotency-Key` and reuse the same key for the retry. The header is optional. If you omit it, each request is treated as a new withdrawal request. ## OpenAPI ````yaml /api-reference/openapi_v3_pws.json post /v1/accounts/{account_id}/funds/withdrawals 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: >- On-demand conversions between bank accounts and account balances, or from account balances to 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: 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: 'Inspect a customer''s portfolio: balances, valuations, and transactions.' - 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}/funds/withdrawals: post: tags: - Funds summary: Create withdrawal description: > Creates a cryptocurrency withdrawal from the selected account to a registered funding address. Optionally supply `fee_token` from [Calculate funding fees](/api-reference/funds/calculate-funding-fees) to reuse a quote's fee terms. To safely retry a request with an unknown outcome, supply a UUIDv4 `Idempotency-Key` and reuse the same key for the retry. The header is optional. If you omit it, each request is treated as a new withdrawal request. operationId: createWithdrawal parameters: - name: account_id in: path required: true description: Public identifier of the account that will send the withdrawal. example: WVSD33HRMGSZUBM7 schema: type: string minLength: 1 maxLength: 64 - name: Idempotency-Key in: header required: false description: >- Optional client-generated UUIDv4 for safe retries. Sent as the `Idempotency-Key` HTTP header. Reuse the same key after a timeout or another unknown outcome. If omitted, each request is treated as a new withdrawal request. example: 550e8400-e29b-41d4-a716-446655440000 schema: type: string format: uuid pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateWithdrawalBody' examples: bitcoin-method: summary: Withdraw Bitcoin through a specific funding method value: scope: method_id: 2fa11f79-eeba-4d4e-afda-029abff6e29e address_id: AB12345-6789A-BCDEFG symbol: BTC amount: '0.01000000' fee_token: eyJ3aXRoZHJhd2FsX2ZlZSI6Ii4uLiJ9 bitcoin-network: summary: Withdraw Bitcoin through a network with one eligible method value: scope: network_id: 6d7f9c7e-588d-4e56-a6f7-f1e9ada7e639 address_id: AB12345-6789A-BCDEFG symbol: BTC amount: '0.01000000' responses: '201': description: Withdrawal created for the selected account. 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/CreateWithdrawalResult' examples: bitcoin: summary: Bitcoin withdrawal created value: data: withdrawal_id: FTSBuuG-9BctU4m3Emt88submmZVKY net_amount: symbol: BTC name: Bitcoin type: crypto amount: '0.00995000' gross_amount: symbol: BTC name: Bitcoin type: crypto amount: '0.01000000' fee: symbol: BTC name: Bitcoin type: crypto amount: '0.00005000' '400': description: >- Request validation failed or the withdrawal could not be created for the requested method, address, asset, or amount. 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: summary: Invalid request value: error: type: funding_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b status: 400 code: bad_request causes: - field: asset_symbol message: must contain between 1 and 16 characters insufficient-funds: summary: Insufficient balance value: error: type: funding_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b status: 400 code: bad_request causes: - field: amount message: exceeds the available balance amount-too-small: summary: Amount below the withdrawal minimum value: error: type: funding_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b status: 400 code: bad_request causes: - field: amount message: is below the minimum for this method incompatible-address: summary: Address is not compatible with the method value: error: type: funding_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b status: 400 code: bad_request causes: - field: address_id message: must identify a compatible saved funding address unsupported-asset: summary: Unsupported withdrawal asset value: error: type: funding_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b status: 400 code: bad_request causes: - field: symbol message: is not supported for crypto withdrawals invalid-fee-token: summary: Invalid withdrawal fee token value: error: type: funding_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b status: 400 code: bad_request causes: - field: fee_token message: must be a valid withdrawal fee quote token fee-token-network-scope: summary: Fee token used with network scope value: error: type: funding_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b status: 400 code: bad_request causes: - field: scope message: must use method_id when fee_token is supplied '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: summary: Authentication failed value: error: type: funding_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b status: 401 code: 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: summary: Caller is not allowed value: error: type: funding_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b status: 403 code: forbidden '409': description: >- The withdrawal requires address-ownership verification, or the account has an active Global Settings Lock. 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: oneOf: - $ref: '#/components/schemas/WithdrawalVerificationRequiredError' title: Address-ownership verification required - $ref: '#/components/schemas/WithdrawalAccountSettingsLockedError' title: Account settings locked examples: verification-required: summary: Address-ownership verification required value: verification_methods: - self_attestation - satoshi_test - digital_signature error: type: funding_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b status: 409 code: withdrawal_verification_required account-settings-locked: summary: Account settings locked value: error: type: funding_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b status: 409 code: withdrawal_account_settings_locked '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: summary: Rate limit exceeded value: error: type: funding_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b status: 429 code: 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: summary: Internal server error value: error: type: funding_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b status: 500 code: internal '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: summary: Service unavailable value: error: type: funding_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b status: 503 code: unavailable '504': description: Request 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: summary: Request deadline exceeded value: error: type: funding_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b status: 504 code: deadline_exceeded security: - ApiKey: [] ApiSign: [] ApiNonce: [] components: schemas: CreateWithdrawalBody: description: >- Funding scope, saved funding address, asset symbol, gross amount, and optional fee token for a normal crypto withdrawal. type: object required: - scope - address_id - symbol - amount properties: scope: $ref: '#/components/schemas/CreateWithdrawalScope' description: Method or network scope used for the withdrawal. address_id: description: >- Stable identifier of a previously registered funding address owned by the selected account. type: string minLength: 20 maxLength: 20 pattern: ^AB[A-Za-z0-9]{5}-[A-Za-z0-9]{5}-[A-Za-z0-9]{6}$ symbol: description: >- Public asset symbol to withdraw. Crypto and stablecoin assets are supported in this operation. type: string minLength: 1 maxLength: 16 amount: description: >- Gross decimal amount debited from the account, inclusive of the fee, represented as a string to preserve precision. type: string minLength: 1 maxLength: 64 pattern: ^[0-9]+(\.[0-9]+)?$ fee_token: $ref: '#/components/schemas/WithdrawalFeeToken' description: >- Fee token from a quote whose fee terms this withdrawal should reuse. Requires `scope.method_id`; cannot be used with network scope. A different amount than the quote does not invalidate the token, but changes the fee charged. Omit to have Funding calculate the fee at creation. CreateWithdrawalResult: description: Withdrawal created for the selected account. type: object required: - data properties: data: $ref: '#/components/schemas/Withdrawal' 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' WithdrawalVerificationRequiredError: description: >- The saved crypto address requires address-ownership verification before it can receive the withdrawal. type: object required: - error - verification_methods properties: error: $ref: '#/components/schemas/WithdrawalVerificationRequiredErrorDetail' verification_methods: description: >- Verification methods that can satisfy the address-ownership requirement. type: array minItems: 1 uniqueItems: true items: description: >- Address-ownership verification method that can unblock the withdrawal. type: string enum: - self_attestation - satoshi_test - digital_signature WithdrawalAccountSettingsLockedError: description: >- Withdrawal cannot be created because the account has an active Global Settings Lock, which temporarily blocks security-sensitive changes. type: object required: - error properties: error: $ref: '#/components/schemas/WithdrawalAccountSettingsLockedErrorDetail' 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 CreateWithdrawalScope: description: >- Funding method or network to use for the withdrawal. Supply exactly one identifier. Network scope resolves only when exactly one method is available for the asset. type: object properties: method_id: description: >- Crypto or stablecoin withdrawal funding method identifier returned by the withdrawal-methods endpoint. type: string format: uuid network_id: description: >- Funding network identifier returned by the withdrawal-methods endpoint. type: string format: uuid WithdrawalFeeToken: description: >- Opaque, short-lived token returned by [Calculate funding fees](/api-reference/funds/calculate-funding-fees), pinning that quote's fee terms rather than an absolute fee. It can become invalid when it expires, or when it is used with a different method, user, or account. Treat this value as sensitive: do not inspect, modify, or log it, and do not share it between users. type: string minLength: 1 maxLength: 2000 Withdrawal: description: >- Created Funding withdrawal, including the Portfolio correlation identifier and execution-time amounts. type: object required: - withdrawal_id - net_amount - gross_amount - fee properties: withdrawal_id: description: >- Opaque Funding withdrawal identifier. Use it as `reference.id` with `reference.kind=funding` when retrieving the corresponding Portfolio transaction. type: string minLength: 1 maxLength: 64 net_amount: $ref: '#/components/schemas/FundingAmount' description: Amount sent after fees. gross_amount: $ref: '#/components/schemas/FundingAmount' description: >- Total amount deducted, including fees. Equals the submitted `amount` for same-asset crypto fees. fee: $ref: '#/components/schemas/FundingAmount' description: >- Fee charged for the withdrawal. With a valid `fee_token`, Funding calculates this absolute fee from the token's fee terms and the submitted withdrawal amount; otherwise Funding uses the current fee terms. 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 WithdrawalVerificationRequiredErrorDetail: description: Withdrawal address-ownership verification required error details. type: object required: - type - status - instance - code properties: type: description: Machine-readable error class for the Funding API. type: string enum: - funding_error status: description: HTTP status code returned for this error. type: integer format: int32 enum: - 409 instance: description: Request identifier for this error occurrence. type: string code: description: Stable machine-readable error code. type: string enum: - withdrawal_verification_required doc_url: description: Link to documentation for this error, when available. type: string format: uri WithdrawalAccountSettingsLockedErrorDetail: description: Withdrawal account settings locked error details. type: object required: - type - status - instance - code properties: type: description: Machine-readable error class for the Funding API. type: string enum: - funding_error status: description: HTTP status code returned for this error. type: integer format: int32 enum: - 409 instance: description: Request identifier for this error occurrence. type: string code: description: Stable machine-readable error code. type: string enum: - withdrawal_account_settings_locked doc_url: description: Link to documentation for this error, when available. type: string format: uri FundingAmount: description: Decimal amount denominated in an asset. type: object required: - symbol - type - amount properties: symbol: description: Asset symbol the amount is denominated in. type: string minLength: 1 maxLength: 16 name: description: Human-readable English asset name. type: string minLength: 1 maxLength: 64 type: $ref: '#/components/schemas/AssetType' description: Public asset classification. amount: description: Decimal amount represented as a string to preserve precision. type: string minLength: 1 maxLength: 64 pattern: ^[0-9]+(\.[0-9]+)?$ 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 AssetType: description: Asset classification for portfolio resources. type: string enum: - fiat - crypto - xstock - stablecoin - equity headers: TraceId: description: Trace identifier for the request. Include it when contacting support. schema: type: string example: 4bf92f3577b34da6a3ce929d0e0e4736 StrictTransportSecurity: description: >- Enforces HTTPS for the configured period. Always `max-age=63072000; includeSubDomains; preload`. schema: type: string example: max-age=63072000; includeSubDomains; preload CacheControl: description: Prevents caching of sensitive financial data. Always `no-store`. schema: type: string enum: - no-store example: no-store 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. ````