> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onstacks.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Transfers

> Preview withdrawals, create transfer activities, approve or cancel transfers, and reconcile status.

Transfers create durable local activity records, reserve available local balance, and submit to BlockOps only after local state commits.

## Preview a withdrawal

Use `POST /v1/wallets/{walletId}/withdrawal/preview?environment=sandbox`.

```json theme={null}
{
  "network_code": "ethereum_sepolia",
  "asset": "USDC",
  "amount": "1000000",
  "to_address": "0xabc..."
}
```

The response includes the source wallet, network, asset, amount in base units, destination address, available balance fields, and provider.

## Create a transfer

Use `POST /v1/transfers?environment=sandbox`.

```json theme={null}
{
  "wallet_id": "00000000-0000-0000-0000-000000000000",
  "network_code": "ethereum_sepolia",
  "asset": "USDC",
  "amount": "1000000",
  "to_address": "0xabc..."
}
```

The response returns `activity_id` and the current transfer status.

## Read transfer status

Use `GET /v1/transfers/{activityId}?environment=sandbox` to read transfer detail and approval state.

Use `POST /v1/transfers/{activityId}/refresh?environment=sandbox` to refresh provider status for a transfer activity.

## Approve or cancel a transfer

Use:

| Endpoint                                  | Purpose                                                            |
| ----------------------------------------- | ------------------------------------------------------------------ |
| `POST /v1/transfers/{activityId}/approve` | Approve a queued transfer or provider-pending BlockOps withdrawal. |
| `POST /v1/transfers/{activityId}/cancel`  | Cancel a queued transfer or provider-pending BlockOps withdrawal.  |

Both endpoints accept the `environment` query parameter.

## Transfer intents

Transfer intents are a read-only beta surface over wallet-backed transfer flows.

| Endpoint                                      | Purpose                                                                                |
| --------------------------------------------- | -------------------------------------------------------------------------------------- |
| `GET /v1/transfer-intents`                    | List persisted transfer intents.                                                       |
| `GET /v1/transfer-intents/{transferIntentId}` | Get normalized intent detail and the underlying wallet transfer detail when available. |

## Wallet transaction history

Use:

| Endpoint                                  | Purpose                                                |
| ----------------------------------------- | ------------------------------------------------------ |
| `GET /v1/wallets/{walletId}/withdrawals`  | List withdrawal activities for a wallet.               |
| `GET /v1/wallets/{walletId}/transactions` | List deposit and withdrawal transactions for a wallet. |
| `GET /v1/transactions/{transactionId}`    | Get a deposit or withdrawal transaction detail.        |