---
title: "Transfer"
description: "Initiate a transfer between internal accounts, external accounts, or crypto wallets."
protocol: rest
method: POST
endpoint: "/v1/transfer"
baseUrl: "https://api.gravv.xyz"
group: "Transfer"
auth:
  label: "Api-Key"
  name: "Api-Key"
  in: header
---

# Transfer

<Endpoint method="POST" path="/v1/transfer" />

Initiate a transfer between internal accounts, external accounts, or crypto wallets.

## Headers

<ParamField name="Idempotency-Key" header="Idempotency-Key" type="string" required>
  Required for POST requests. Reuse the key only when retrying the same operation with an identical payload.
</ParamField>

## Request Body

<ParamField name="source" body="source" type="object" required>
  Source of the transfer

  <Expandable title="properties">
    <ParamField name="source_type" body="source.source_type" type="string" required>
      source can be `internal_account` or `internal_crypto_wallet`

      Possible values: `internal_account`, `internal_crypto_wallet`
    </ParamField>

    <ParamField name="crypto_asset" body="source.crypto_asset" type="string">
      Optional crypto asset type
    </ParamField>

    <ParamField name="id" body="source.id" type="string" required>
      Use internal account ID or wallet ID
    </ParamField>

  </Expandable>
</ParamField>

<ParamField name="destination" body="destination" type="oneOf" required>

  One of the following variants:

  <Expandable title="External Account Destination">
    <ParamField name="id" body="destination.id" type="string" required>
      External account ID
    </ParamField>

    <ParamField name="destination_type" body="destination.destination_type" type="string" required>
      The transfer destination type

      Possible values: `external_account`
    </ParamField>

    <ParamField name="rail" body="destination.rail" type="string">
      The transfer rail type

      Possible values: `ach`, `wire`, `sepa`, `swift`, `fps`, `globalbank`
    </ParamField>

  </Expandable>

  <Expandable title="Internal Account Destination">
    <ParamField name="id" body="destination.id" type="string" required>
      Internal account ID
    </ParamField>

    <ParamField name="destination_type" body="destination.destination_type" type="string" required>

      Possible values: `internal_account`
    </ParamField>

  </Expandable>

  <Expandable title="Crypto Wallet Destination">
    <ParamField name="blockchain_network" body="destination.blockchain_network" type="string" required>
      Blockchain network (e.g., polygon, ethereum)

      Possible values: `polygon`, `ethereum`, `avalanche`, `stellar`, `solana`, `sui`, `tron`
    </ParamField>

    <ParamField name="wallet_address" body="destination.wallet_address" type="string" required>
      Crypto wallet address
    </ParamField>

    <ParamField name="destination_type" body="destination.destination_type" type="string" required>

      Possible values: `crypto_wallet`
    </ParamField>

    <ParamField name="blockchain_memo" body="destination.blockchain_memo" type="string">
      Required for only stellar network
    </ParamField>

  </Expandable>

  <Expandable title="Card Destination">
    <ParamField name="id" body="destination.id" type="string" required>
      Recipient card ID
    </ParamField>

    <ParamField name="destination_type" body="destination.destination_type" type="string" required>
      The transfer destination type

      Possible values: `card`
    </ParamField>

  </Expandable>
</ParamField>

<ParamField name="amount" body="amount" type="number" required>
  Transfer amount
</ParamField>

<ParamField name="additional_information" body="additional_information" type="object">
  Additional remitter information required for external bank account and mobile money beneficiaries

  <Expandable title="properties">
    <ParamField name="remitter_full_name" body="additional_information.remitter_full_name" type="string">
      Full name of the person sending the transfer
    </ParamField>

    <ParamField name="remitter_country" body="additional_information.remitter_country" type="string">
      Country code of the remitter (ISO 3166-1 alpha-2)
    </ParamField>

    <ParamField name="remitter_document_number" body="additional_information.remitter_document_number" type="string">
      Document/ID number of the remitter
    </ParamField>

    <ParamField name="remitter_document_issue_date" body="additional_information.remitter_document_issue_date" type="string">
      Date when the remitter's document was issued
    </ParamField>

    <ParamField name="remitter_document_expiry_date" body="additional_information.remitter_document_expiry_date" type="string">
      Date when the remitter's document expires
    </ParamField>

    <ParamField name="remitter_date_of_birth" body="additional_information.remitter_date_of_birth" type="string">
      Date of birth of the remitter
    </ParamField>

    <ParamField name="remitter_address" body="additional_information.remitter_address" type="object">
      Physical address of the remitter

      <Expandable title="properties">
        <ParamField name="address_line1" body="additional_information.remitter_address.address_line1" type="string">
          Primary address line
        </ParamField>

        <ParamField name="city" body="additional_information.remitter_address.city" type="string">
          City name
        </ParamField>

        <ParamField name="state" body="additional_information.remitter_address.state" type="string">
          State or province code
        </ParamField>

        <ParamField name="postal_code" body="additional_information.remitter_address.postal_code" type="string">
          Postal or ZIP code
        </ParamField>

        <ParamField name="country" body="additional_information.remitter_address.country" type="string">
          Country code (ISO 3166-1 alpha-2)
        </ParamField>

      </Expandable>
    </ParamField>

    <ParamField name="remitter_nationality" body="additional_information.remitter_nationality" type="string">
      Nationality of the remitter (ISO 3166-1 alpha-2 country code)
    </ParamField>

  </Expandable>
</ParamField>

<ParamField name="description" body="description" type="string" required>
  Transfer description
</ParamField>

<ParamField name="customer_id" body="customer_id" type="string" required>
  Customer initiating the transfer
</ParamField>

<ParamField name="client_reference" body="client_reference" type="string" required>
  Optional client reference for reconciliation
</ParamField>

### Request Examples

<RequestExample>

```json title="GlobalRemittance"
{
  "source": {
    "source_type": "internal_account",
    "id": "b9c2cb0d-e09a-496f-8655-d8c4b7aaf2f8"
  },
  "destination": {
    "id": "70c337ad-e3e8-4a90-9de7-7f3e6bc2aac8",
    "destination_type": "external_account"
  },
  "amount": 1.5,
  "additional_information": {
    "remitter_full_name": "John Doe",
    "remitter_country": "US",
    "remitter_document_number": "A123456789",
    "remitter_document_issue_date": "2020-01-15",
    "remitter_document_expiry_date": "2030-01-15",
    "remitter_date_of_birth": "1990-06-25",
    "remitter_address": {
      "address_line1": "123 Main Street",
      "city": "New York",
      "state": "NY",
      "postal_code": "10001",
      "country": "US"
    },
    "remitter_nationality": "US"
  },
  "client_reference": "099283849s",
  "description": "Transfer Testing",
  "customer_id": "bb6c6022-f1d8-492f-80f0-7547134bb42f"
}
```

```json title="InternalTransfer"
{
  "source": {
    "source_type": "internal_account",
    "id": "b9c2cb0d-e09a-496f-8655-d8c4b7aaf2f8"
  },
  "destination": {
    "id": "915a6953-49a1-4a78-b29d-56d401d9f22a",
    "destination_type": "internal_account"
  },
  "amount": 1,
  "additional_information": {
    "remitter_full_name": "John Doe",
    "remitter_country": "US",
    "remitter_document_number": "A123456789",
    "remitter_document_issue_date": "2020-01-15",
    "remitter_document_expiry_date": "2030-01-15",
    "remitter_date_of_birth": "1990-06-25",
    "remitter_address": {
      "address_line1": "123 Main Street",
      "city": "New York",
      "state": "NY",
      "postal_code": "10001",
      "country": "US"
    },
    "remitter_nationality": "US"
  },
  "description": "Transfer Testing",
  "customer_id": "bb6c6022-f1d8-492f-80f0-7547134bb42f",
  "client_reference": "hellowe2"
}
```

```json title="CryptoTransfer"
{
  "source": {
    "source_type": "internal_account",
    "id": "b9c2cb0d-e09a-496f-8655-d8c4b7aaf2f8"
  },
  "destination": {
    "blockchain_network": "polygon",
    "destination_type": "crypto_wallet",
    "wallet_address": "0x25a4c9853e761753ae18d6871731e305b8b0b2a4"
  },
  "amount": 2,
  "description": "Transfer Testing",
  "customer_id": "bb6c6022-f1d8-492f-80f0-7547134bb42f",
  "client_reference": "2893843"
}
```

```json title="CryptoToCardTransfer"
{
  "source": {
    "source_type": "crypto_wallet",
    "id": "67e169c0-547f-410d-8e18-f616b6822d70"
  },
  "destination": {
    "destination_type": "card",
    "id": "3397bab8-0f2b-4721-b15b-8c71860f01f9"
  },
  "amount": 3,
  "description": "card funding",
  "customer_id": "04dfb2e5-1274-4214-b5fd-3415fde7dc18",
  "client_reference": "cardtransfer1234"
}
```

</RequestExample>

## Responses

| Status | Description |
| --- | --- |
| `200` | Transfer successful |
| `400` | Bad request |

### 200 response

<ResponseField name="data" type="object">

  <Expandable title="properties">
    <ResponseField name="amount" type="string">
      Transfer amount as a decimal string.
    </ResponseField>

    <ResponseField name="reference" type="string">
      Unique transfer reference.
    </ResponseField>

    <ResponseField name="date_created" type="string">
      ISO 8601 timestamp when the transfer was created.
    </ResponseField>

    <ResponseField name="transfer_status" type="string">
      Current status of the transfer.

      Possible values: `pending`, `failed`, `completed`
    </ResponseField>

    <ResponseField name="transaction_id" type="string">
      ID of the associated transaction record.
    </ResponseField>

    <ResponseField name="local_amount" type="string,null">
      Equivalent amount in the recipient's local currency, if applicable.
    </ResponseField>

    <ResponseField name="local_currency" type="string,null">
      Three-letter ISO 4217 code for the recipient's local currency, if applicable.
    </ResponseField>

  </Expandable>
</ResponseField>

<ResponseField name="error" type="string,null">
</ResponseField>

<ResponseExample>

```json title="Response"
{
  "data": {
    "amount": "1.5",
    "reference": "550e8400-e29b-41d4-a716-446655440000",
    "date_created": "2024-01-15T10:30:00Z",
    "transfer_status": "pending",
    "transaction_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "local_amount": null,
    "local_currency": null
  },
  "error": null
}
```

</ResponseExample>

### 400 response

<ResponseField name="data" type="null">
</ResponseField>

<ResponseField name="error" type="string">
</ResponseField>

<ResponseExample>

```json title="Response"
{
  "data": null,
  "error": "invalid request payload"
}
```

</ResponseExample>

## Authorization

- **ApiKeyAuth**