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

# Create Token Transfer

> Move tokens between custodial and external addresses. Only available for tokenization (self-attested) accounts.

```
POST /accounts/{account_id}/tokens/transfers
```

Required scope: `self_attested_tokens:transfer`.

Use an `Idempotency-Key` header. Only available for tokenization (self-attested) accounts.

## Path parameters

| Name         | Type   | Description                                                |
| ------------ | ------ | ---------------------------------------------------------- |
| `account_id` | string | KSUID of the tokenization account performing the transfer. |

## Request body

| Field                       | Type   | Required | Description                                     |
| --------------------------- | ------ | -------- | ----------------------------------------------- |
| `amount`                    | string | Yes      | Amount to transfer, as a decimal string.        |
| `source.address_id`         | string | Yes      | KSUID of the source address holding the tokens. |
| `source.value_type`         | string | Yes      | The token value type (e.g., `MY_TOKEN`).        |
| `source.transfer_type`      | string | Yes      | The chain the tokens are held on.               |
| `destination.address_id`    | string | Yes      | KSUID of the destination address.               |
| `destination.value_type`    | string | Yes      | The token value type on the destination side.   |
| `destination.transfer_type` | string | Yes      | The chain the destination address is on.        |

## Example request

```bash theme={null}
curl --request POST \
  --url https://api.brale.xyz/accounts/{account_id}/tokens/transfers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <uuid>' \
  --data '{
    "amount": "1000.50",
    "source": {
      "address_id": "2VcUIIsgARwVbEGlIYbhg6fGG57",
      "value_type": "MY_TOKEN",
      "transfer_type": "base"
    },
    "destination": {
      "address_id": "2srdkF6Sm8TWOJpWt1oNlTVes1w",
      "value_type": "MY_TOKEN",
      "transfer_type": "base"
    }
  }'
```

## Example success response

```json theme={null}
{
  "id": "2XyTransferKsuid00000000000",
  "status": "pending",
  "amount": "1000.50",
  "source": {
    "address_id": "2VcUIIsgARwVbEGlIYbhg6fGG57",
    "value_type": "MY_TOKEN",
    "transfer_type": "base"
  },
  "destination": {
    "address_id": "2srdkF6Sm8TWOJpWt1oNlTVes1w",
    "value_type": "MY_TOKEN",
    "transfer_type": "base"
  },
  "created_at": "2025-01-15T12:00:00Z"
}
```

## Example error response

```json theme={null}
{
  "status": 400,
  "title": "Bad Request",
  "detail": "Source and destination value_type must match for a token transfer."
}
```

## Related endpoints

* [List token transfers](/api-reference/brale/list-token-transfers)
* [Get token transfer](/api-reference/brale/get-token-transfer)
* [Tokenization guide](/guides/tokenization)