> ## 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.

# Transfers

> Move assets between accounts in your Payward Services program and reconcile the result through Portfolio.

## Overview

The Transfers API moves an asset from one PWS account to another account in the authenticated caller's program.

Only account-to-account transfers are supported. Email, username-tag, and other recipient types are not supported.

## Prerequisites

* Payward Services API credentials (see the [Authentication guide](/tabs/developer-documentation/get-started/authentication))
* A source account with a sufficient available balance
* A destination account in the same program

## Create a transfer

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

```bash theme={null}
curl -X POST "https://api.services.payward.com/v1/transfers" \
  -H "API-Key: $PWS_API_KEY" \
  -H "API-Nonce: $PWS_API_NONCE" \
  -H "API-Sign: $PWS_API_SIGN" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "WVSD33HRMGSZUBM7",
    "to": "WNPY3PJZYD4L9E7B",
    "asset": "USD",
    "amount": "25.50"
  }'
```

### Response

A successful request returns HTTP `201`:

```json theme={null}
{
  "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`

```bash theme={null}
curl --get "https://api.services.payward.com/v1/accounts/WVSD33HRMGSZUBM7/portfolio/transactions" \
  --data-urlencode "types=transfer" \
  --data-urlencode "start_timestamp=2026-07-23T10:00:00Z" \
  --data-urlencode "end_timestamp=2026-07-23T11:00:00Z" \
  -H "API-Key: $PWS_API_KEY" \
  -H "API-Nonce: $PWS_API_NONCE" \
  -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:

```json theme={null}
{
  "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:

```text theme={null}
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            |
| `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                  |

<Note>**Not yet available.** Transfer creation does not support idempotency keys.</Note>