> ## 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 derivatives transfer

> Move funds between an account's spot and futures balances.

If you aren't sure whether a transfer went through, check both balances or contact Payward Services support before trying again.



## OpenAPI

````yaml /api-reference/openapi_v3_pws.json post /v1/accounts/{account_id}/transfers/derivatives
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: Derivative transfers
    description: Move funds between an account's spot and futures balances.
  - 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}/transfers/derivatives:
    post:
      tags:
        - Derivative transfers
      summary: Create derivatives transfer
      description: >-
        Move funds between an account's spot and futures balances.


        If you aren't sure whether a transfer went through, check both balances
        or contact Payward Services support before trying again.
      operationId: createDerivativesTransfer
      parameters:
        - name: account_id
          in: path
          required: true
          description: >-
            Account whose spot and futures balances you want to move funds
            between. The owner needs an eligible futures balance.
          example: WVSD33HRMGSZUBM7
          schema:
            $ref: '#/components/schemas/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              description: Derivatives transfer request.
              type: object
              required:
                - asset
                - amount
                - from
                - to
              properties:
                asset:
                  description: >-
                    Currency you want to move. It must be supported by the
                    account's futures balance.
                  type: string
                  minLength: 1
                  maxLength: 16
                amount:
                  description: >-
                    Amount to move. You can transfer funds that are available
                    after any holds and collateral requirements.
                  type: string
                  minLength: 1
                  maxLength: 64
                  pattern: ^(0*[1-9][0-9]*(\.[0-9]+)?|0+\.(0?[1-9][0-9]*))$
                from:
                  $ref: '#/components/schemas/DerivativesTransferLocation'
                  description: >-
                    Balance the funds move from. Choose a different balance from
                    `to`.
                to:
                  $ref: '#/components/schemas/DerivativesTransferLocation'
                  description: >-
                    Balance the funds move to. Both balances must belong to the
                    same account owner.
            examples:
              spot-to-futures:
                summary: Move funds from spot to futures
                value:
                  asset: USD
                  amount: '25.50'
                  from: spot
                  to: futures
              futures-to-spot:
                summary: Move funds from futures to spot
                value:
                  asset: USD
                  amount: '25.50'
                  from: futures
                  to: spot
      responses:
        '200':
          description: Your transfer has been accepted for processing.
          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/CreateDerivativesTransferEnvelope'
              examples:
                accepted:
                  summary: Derivatives transfer accepted
                  value:
                    data:
                      transfer_id: FTSBuuG-9BctU4m3Emt88submmZVKY
                      status: accepted
        '400':
          description: >-
            Request validation failed or the derivatives transfer could not be
            processed.
          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:
                amount-too-small:
                  summary: Amount below the derivatives transfer minimum
                  value:
                    error:
                      type: funding_error
                      instance: 5f4d2a8e-91a4-4d6c-8a3e-4d5e6f7a8b9c
                      status: 400
                      code: bad_request
                      causes:
                        - field: amount
                          message: is below the minimum for this transfer method
                unsupported-asset:
                  summary: Unsupported derivatives transfer asset
                  value:
                    error:
                      type: funding_error
                      instance: 5f4d2a8e-91a4-4d6c-8a1e-2c3f4a5b6c7d
                      status: 400
                      code: bad_request
                      causes:
                        - field: asset
                          message: is not supported for futures transfers
                insufficient-balance:
                  summary: Insufficient spot balance
                  value:
                    error:
                      type: funding_error
                      instance: 5f4d2a8e-91a4-4d6c-8a2e-3c4f5a6b7c8d
                      status: 400
                      code: bad_request
                      causes:
                        - field: amount
                          message: exceeds the available balance
                insufficient-futures-balance:
                  summary: Insufficient futures balance available for transfer
                  value:
                    error:
                      type: funding_error
                      instance: 5f4d2a8e-91a4-4d6c-8a2f-3c4f5a6b7c8d
                      status: 400
                      code: bad_request
                      causes:
                        - field: amount
                          message: exceeds the futures balance available for transfer
                futures-unavailable:
                  summary: No eligible futures destination balance
                  value:
                    error:
                      type: funding_error
                      instance: 5f4d2a8e-91a4-4d6c-8a30-3c4f5a6b7c8d
                      status: 400
                      code: bad_request
                      causes:
                        - field: to
                          message: >-
                            is unavailable because the account owner has no
                            eligible futures balance
                transfer-rejected:
                  summary: Futures transfer rejected
                  value:
                    error:
                      type: funding_error
                      instance: 5f4d2a8e-91a4-4d6c-8a2f-3c4f5a6b7c8d
                      status: 400
                      code: bad_request
                      causes:
                        - field: transfer
                          message: cannot be completed for the selected futures balance
                invalid-direction:
                  summary: Source and destination select the same balance
                  value:
                    error:
                      type: funding_error
                      instance: 5f4d2a8e-91a4-4d6c-8a2f-3c4f5a6b7c8d
                      status: 400
                      code: bad_request
                      causes:
                        - field: from
                          message: >-
                            must form either the `spot` to `futures` or
                            `futures` to `spot` route
        '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
        '404':
          description: >-
            The selected account does not exist or cannot be selected by the
            authenticated caller.
          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:
                derivatives-transfer-account-not-found:
                  summary: Derivatives transfer account not found
                  value:
                    error:
                      type: funding_error
                      instance: 5f4d2a8e-91a4-4d6c-8a4e-5f6a7b8c9d0e
                      status: 404
                      code: 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:
                  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:
    AccountId:
      type: string
      description: Canonical identifier for an account in the Payward public API.
      minLength: 14
      maxLength: 42
    DerivativesTransferLocation:
      description: Spot or futures balance associated with the selected account.
      type: string
      enum:
        - spot
        - futures
    CreateDerivativesTransferEnvelope:
      description: Derivatives transfer response.
      type: object
      required:
        - data
      properties:
        data:
          $ref: '#/components/schemas/DerivativesTransfer'
          description: Transfer result.
    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'
    NotFoundError:
      description: Requested resource is not available to the selected account.
      type: object
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/NotFoundErrorDetail'
    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
    DerivativesTransfer:
      description: Derivatives transfer result.
      type: object
      required:
        - status
      properties:
        transfer_id:
          description: Transfer reference to keep for tracking and support.
          type: string
          minLength: 1
          maxLength: 128
        status:
          $ref: '#/components/schemas/DerivativesTransferStatus'
          description: >-
            `accepted` means your transfer has been accepted for processing.
            Check the destination balance to confirm the funds have arrived.
    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
    NotFoundErrorDetail:
      description: Structured resource-not-found error details.
      type: object
      required:
        - type
        - status
        - instance
        - code
      properties:
        type:
          description: Machine-readable error class for the API that handled the request.
          type: string
          enum:
            - funding_error
            - portfolio_error
        status:
          description: HTTP status code returned for this error.
          type: integer
          format: int32
          enum:
            - 404
        instance:
          description: Request identifier for this error occurrence.
          type: string
        code:
          description: Stable machine-readable error code.
          type: string
          enum:
            - not_found
        doc_url:
          description: Link to documentation for this error, when available.
          type: string
          format: uri
        causes:
          description: Field-level causes for validation errors, when available.
          type: array
          items:
            $ref: '#/components/schemas/ErrorCause'
    DerivativesTransferStatus:
      description: Status of your transfer request.
      type: string
      enum:
        - accepted
        - not_required
    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
    ErrorCause:
      description: Field-level validation failure.
      type: object
      required:
        - field
        - message
      properties:
        field:
          description: Request field that failed validation.
          type: string
        message:
          description: Human-readable explanation of the validation failure.
          type: string
  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.

````