Transfers

Overview

Use POST /v1/transfers to move an asset between accounts in your program. Use POST /v1/accounts/{account_id}/transfers/derivatives to move funds between one account’s spot and futures balances.

Transfer between accounts

The source and destination must be distinct accounts. They may belong to the same user or to different users, but both must be in the authenticated caller’s program. Email, username-tag, and other recipient types are not supported.

Prerequisites

A source account with a sufficient available balance
A destination account in the same program

The curl examples read these environment variables:

PWS_BASE_URL: the API base URL. Set it to the sandbox or production base URL, listed in Environments.
PWS_API_KEY: your API key.
PWS_API_TIMESTAMP and PWS_API_SIGN: the timestamp and signature of each request. To compute them, see Authentication.
Compute PWS_API_SIGN over the exact -d string, including its line breaks and indentation, and over the exact path and query in the URL. Each request needs a new PWS_API_TIMESTAMP and PWS_API_SIGN.

Create a transfer

Send POST /v1/transfers with the source account, destination account, asset symbol, and decimal amount.

curl -X POST "$PWS_BASE_URL/v1/transfers" \
  -H "API-Key: $PWS_API_KEY" \
  -H "API-Timestamp: $PWS_API_TIMESTAMP" \
  -H "API-Sign: $PWS_API_SIGN" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "WVSD33HRMGSZUBM7",
    "to": "WNPY3PJZYD4L9E7B",
    "asset": "USD",
    "amount": "25.50"
  }'

Make retries idempotent

Generate one UUIDv4 for each intended transfer. Reuse that same key only when retrying the identical request.

The same key and request prevent a second transfer execution. The retry returns the transfer’s current recorded outcome.
The same key with different, otherwise valid transfer parameters returns 409 Conflict with code idempotency_conflict.
A keyed retry does not replay the original HTTP status and body. The response does not include Idempotent-Replayed.
A request rejected before it is recorded may leave the key available for another request.
A recorded key remains reserved beyond 24 hours. Never reuse it for a new transfer.

If you omit Idempotency-Key, transfer creation is not idempotent. Do not automatically retry a timeout or another unknown outcome. Reconcile the source account through Portfolio or contact Payward Services support first.

Response

A successful request returns HTTP 201:

{
  "data": {
    "transfer_id": "TRYCMN7-WXKJM-F47YIM",
    "status": "pending"
  }
}

Status	Description
`pending`	The transfer is still being processed.
`complete`	The transfer creation operation completed.
`failed`	The transfer creation operation could not be completed.

transfer_id is an opaque originating reference. It is distinct from the Portfolio transaction ID.

Reconcile through Portfolio

Transfer creation and Portfolio visibility are asynchronous. A create response with status: complete does not guarantee that the Portfolio transaction is visible yet. Poll GET /v1/accounts/{account_id}/portfolio/transactions using:

the request’s from account as account_id
types=transfer
a time range that includes the create request
no statuses filter, or a filter that includes in_progress

curl -X GET "$PWS_BASE_URL/v1/accounts/WVSD33HRMGSZUBM7/portfolio/transactions?types=transfer&start_timestamp=2026-07-23T10%3A00%3A00Z&end_timestamp=2026-07-23T11%3A00%3A00Z" \
  -H "API-Key: $PWS_API_KEY" \
  -H "API-Timestamp: $PWS_API_TIMESTAMP" \
  -H "API-Sign: $PWS_API_SIGN"

Portfolio transactions are account-relative. The from account response contains spend, while the to account response contains receive. The example below queries the from account, so it shows only spend. When the transaction appears, its reference links it to the create response:

{
  "data": [
    {
      "id": "TXYCMN8-ABCD2-EFGH3I",
      "timestamp": "2026-07-23T10:15:30Z",
      "type": "transfer",
      "status": "in_progress",
      "reference": {
        "kind": "transfer",
        "id": "TRYCMN7-WXKJM-F47YIM"
      },
      "spend": {
        "sub_total": {
          "symbol": "USD",
          "name": "US Dollar",
          "type": "fiat",
          "amount": "25.50",
          "amount_in_quote": "25.50"
        },
        "total": {
          "symbol": "USD",
          "name": "US Dollar",
          "type": "fiat",
          "amount": "25.50",
          "amount_in_quote": "25.50"
        },
        "timestamp": "2026-07-23T10:15:30Z"
      }
    }
  ],
  "quote_symbol": "USD",
  "quote_type": "fiat"
}

Use the reference for deterministic later lookups:

references[0][kind]=transfer
references[0][id]=TRYCMN7-WXKJM-F47YIM

Reference entries use OR semantics with each other. They combine with types and other filters using AND semantics. Keep these identifiers distinct:

Identifier	Meaning
Portfolio `id` (`TX...`)	The Portfolio transaction identifier.
`reference.id` with `funding`	The originating Funding deposit identifier.
`reference.id` with `transfer`	The `transfer_id` returned by create.

Error handling

HTTP status	Cause
`400 Bad Request`	Invalid request, unsupported asset, or insufficient balance
`401 Unauthorized`	Missing or invalid API credentials
`403 Forbidden`	The caller cannot access an account or operation
`409 Conflict`	Idempotency key conflict or stale conversion rate
`429 Too Many Requests`	Rate limit exceeded
`500 Internal Server Error`	Unexpected service failure
`503 Service Unavailable`	A required service is temporarily unavailable
`504 Gateway Timeout`	A required service did not respond in time

Transfer between spot and futures

Prerequisites

An eligible futures wallet and balance for the account owner
An asset supported by the account’s futures balance
Enough funds available in the source balance after holds and collateral requirements

Create a transfer

Send POST /v1/accounts/{account_id}/transfers/derivatives with a positive decimal amount. Set from and to to move funds from spot to futures or from futures to spot within the same account:

{
  "asset": "USD",
  "amount": "25.50",
  "from": "spot",
  "to": "futures"
}

Swap from and to to move funds back to spot.

Response

A successful request returns HTTP 200:

{
  "data": {
    "transfer_id": "FTSBuuG-9BctU4m3Emt88submmZVKY",
    "status": "accepted"
  }
}

A status of accepted means your transfer has been accepted for processing. Check the destination balance to confirm the funds have arrived.

Track the transfer

Keep the returned transfer_id with the account, asset, amount, direction, and request time. Use it to identify the transfer when contacting Payward Services support. To look for a corresponding Portfolio entry, query GET /v1/accounts/{account_id}/portfolio/transactions with the same account_id used to create the transfer and a time range around the request:

curl -X GET "$PWS_BASE_URL/v1/accounts/WVSD33HRMGSZUBM7/portfolio/transactions?start_timestamp=2026-07-23T10%3A00%3A00Z&end_timestamp=2026-07-23T11%3A00%3A00Z" \
  -H "API-Key: $PWS_API_KEY" \
  -H "API-Timestamp: $PWS_API_TIMESTAMP" \
  -H "API-Sign: $PWS_API_SIGN"

If an entry includes a reference.id matching your transfer_id, keep its Portfolio id and the returned reference.kind for later lookups. For later lookups, pass that pair as references[0][kind] and references[0][id]. Portfolio entries can appear asynchronously and may first have status in_progress. A missing entry does not prove the transfer failed. Check both balances or contact support if the outcome is unclear. See the Portfolio guide for transaction filters.

Retry guidance

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

Error handling

HTTP status	Cause
`400 Bad Request`	Invalid direction or amount, unsupported asset, insufficient funds, or a rejected transfer
`401 Unauthorized`	Missing or invalid API credentials
`403 Forbidden`	The caller cannot access the account or operation
`404 Not Found`	The account does not exist or cannot be selected
`429 Too Many Requests`	Rate limit exceeded
`500 Internal Server Error`	Unexpected service failure
`503 Service Unavailable`	The operation is temporarily unavailable
`504 Gateway Timeout`	The request did not finish within the time limit

For a validation error, use error.causes to identify the affected field. For a timeout or another unknown outcome, follow the retry guidance above before submitting another transfer.

Introduction

Testing

Market data

Accounts

Verifications

Trade

Earn

Payments

Overview

Transfer between accounts

Prerequisites

Create a transfer

Make retries idempotent

Response

Reconcile through Portfolio

Error handling

Transfer between spot and futures

Prerequisites

Create a transfer

Response

Track the transfer

Retry guidance

Error handling

​Overview

​Transfer between accounts

​Prerequisites

​Create a transfer

​Make retries idempotent

​Response

​Reconcile through Portfolio

​Error handling

​Transfer between spot and futures

​Prerequisites

​Create a transfer

​Response

​Track the transfer

​Retry guidance

​Error handling

Overview

Transfer between accounts

Prerequisites

Create a transfer

Make retries idempotent

Response

Reconcile through Portfolio

Error handling

Transfer between spot and futures

Prerequisites

Create a transfer

Response

Track the transfer

Retry guidance

Error handling