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

# Direct Wallet Transfer

> Initiate blockchain-to-blockchain transfers from external wallets to your Devdraft wallets

The Create Direct Wallet Transfer endpoint enables you to initiate blockchain-to-blockchain transfers where the source funds come from an external wallet (not yours) and are deposited directly into one of your Devdraft wallets. This endpoint creates a dynamic transfer that provides source deposit instructions for the sender to follow.

## Endpoint Details

* **Method:** `POST`
* **URL:** `/api/v0/transfers/direct-wallet`
* **Content-Type:** `application/json`

## Authentication

This endpoint requires API key authentication using both:

* `x-client-key`: Your application's client key
* `x-client-secret`: Your application's client secret

## Request Body

<CodeGroup>
  ```json Request theme={null}
  {
    "walletId": "550e8400-e29b-41d4-a716-446655440000",
    "network": "solana",
    "stableCoinCurrency": "usdc",
    "amount": 1000.50
  }
  ```
</CodeGroup>

### Parameters

| Parameter          | Type   | Required | Description                                                                 |
| ------------------ | ------ | -------- | --------------------------------------------------------------------------- |
| walletId           | string | Yes      | The ID of your wallet to receive the transfer                               |
| network            | string | Yes      | Source blockchain network (solana, base, ethereum, polygon, arbitrum, etc.) |
| stableCoinCurrency | string | Yes      | Source stablecoin currency (usdc, eurc)                                     |
| amount             | number | No       | Transfer amount (optional for flexible amount transfers)                    |

### Supported Networks

* **Solana** (`solana`)
* **Base** (`base`)
* **Ethereum** (`ethereum`)
* **Polygon** (`polygon`)
* **Arbitrum** (`arbitrum`)
* **Optimism** (`optimism`)
* **Avalanche C-Chain** (`avalanche_c_chain`)

### Supported Stablecoin Currencies

* **USDC** (`usdc`) - Available on all networks
* **EURC** (`eurc`) - Currently only available on Solana

## Response

### Success Response (201 Created)

<CodeGroup>
  ```json Response theme={null}
  {
    "id": "tr_1234567890abcdef",
    "state": "awaiting_funds",
    "amount": "1000.50",
    "developer_fee": "200.10",
    "on_behalf_of": "cus_bridge123abc",
    "source": {
      "payment_rail": "solana",
      "currency": "usdc",
      "to_address": null,
      "external_account_id": null
    },
    "destination": {
      "payment_rail": "base",
      "currency": "usdc", 
      "to_address": "0x742d35Cc6Ff82a8C2D8D1Da9da17c7eDfD5bE0a3",
      "external_account_id": null
    },
    "source_deposit_instructions": {
      "payment_rail": "solana",
      "currency": "usdc",
      "amount": "1000.50",
      "to_address": "7xKXKRoBrJgCXVb2KhxZZzPHxYMJ4DpHWGQ8RvxS6JEq",
      "deposit_message": "Transfer ID: tr_1234567890abcdef",
      "from_address": null,
      "bank_name": null,
      "bank_address": null,
      "bank_routing_number": null,
      "bank_account_number": null,
      "bank_beneficiary_name": null,
      "bank_beneficiary_address": null
    },
    "receipt": null,
    "created_at": "2024-01-20T10:30:00Z",
    "updated_at": "2024-01-20T10:30:00Z"
  }
  ```
</CodeGroup>

### Response Fields

| Field                         | Type   | Description                                                     |
| ----------------------------- | ------ | --------------------------------------------------------------- |
| id                            | string | Unique transfer identifier                                      |
| state                         | string | Transfer state (awaiting\_funds, processing, completed, failed) |
| amount                        | string | Transfer amount (if fixed)                                      |
| developer\_fee                | string | Developer fee amount (0.8% of transfer amount)                  |
| source                        | object | Source endpoint information                                     |
| destination                   | object | Destination endpoint information                                |
| source\_deposit\_instructions | object | **Critical**: Instructions for the sender                       |
| receipt                       | object | Transfer receipt (available when completed)                     |
| created\_at                   | string | Transfer creation timestamp                                     |
| updated\_at                   | string | Last update timestamp                                           |

## Understanding Source Deposit Instructions

The `source_deposit_instructions` object is the most important part of the response. It contains the exact information that the external sender needs to complete the transfer.

### For Blockchain Networks (Solana, Base, Ethereum, etc.)

<CodeGroup>
  ```json Blockchain Instructions theme={null}
  {
    "source_deposit_instructions": {
      "payment_rail": "solana",
      "currency": "usdc",
      "amount": "1000.50",
      "to_address": "7xKXKRoBrJgCXVb2KhxZZzPHxYMJ4DpHWGQ8RvxS6JEq",
      "deposit_message": "Transfer ID: tr_1234567890abcdef"
    }
  }
  ```
</CodeGroup>

#### Key Fields for Blockchain Instructions

| Field            | Description             | Usage                                        |
| ---------------- | ----------------------- | -------------------------------------------- |
| to\_address      | **Destination address** | Sender must send funds TO this address       |
| currency         | Token to send           | Sender must send this specific stablecoin    |
| amount           | Amount to send          | Exact amount required (if fixed amount)      |
| deposit\_message | Transfer reference      | Include as memo/note if supported by network |

### For Bank/Wire Transfers (ACH, WIRE, SEPA)

<CodeGroup>
  ```json Bank Instructions theme={null}
  {
    "source_deposit_instructions": {
      "payment_rail": "wire",
      "currency": "usd",
      "amount": "1000.50",
      "bank_name": "JPMorgan Chase Bank, N.A.",
      "bank_address": "270 Park Avenue, New York, NY 10017",
      "bank_routing_number": "021000021",
      "bank_account_number": "1234567890",
      "bank_beneficiary_name": "Devdraft Network Inc",
      "bank_beneficiary_address": "123 Devdraft Street, San Francisco, CA 94105",
      "deposit_message": "Transfer ID: tr_1234567890abcdef"
    }
  }
  ```
</CodeGroup>

#### Key Fields for Bank Instructions

| Field                   | Description             | Usage                             |
| ----------------------- | ----------------------- | --------------------------------- |
| bank\_name              | Receiving bank name     | For wire transfer forms           |
| bank\_routing\_number   | Bank routing/SWIFT code | Required for transfers            |
| bank\_account\_number   | Account number          | Destination account               |
| bank\_beneficiary\_name | Account holder name     | Beneficiary information           |
| deposit\_message        | **Critical reference**  | Must be included in transfer memo |

## How Source Deposit Instructions Work

### 1. Dynamic Transfer Creation

When you create a direct wallet transfer, the system:

* Generates a unique temporary receiving address/account
* Creates deposit instructions for the sender
* Sets up monitoring for incoming funds

### 2. Sender Instructions

You provide the `source_deposit_instructions` to the external sender, who must:

* Send the exact `currency` and `amount` (specified)
* Send TO the provided `to_address` (blockchain) or bank details
* Include the `deposit_message` as memo/reference

### 3. Automatic Processing

Once funds are received:

* System detects the incoming deposit
* Automatically converts and transfers to your destination wallet
* Updates transfer state to `completed`
* Provides final receipt with all fees and amounts

## Transfer States

| State           | Description                                | Next Action                            |
| --------------- | ------------------------------------------ | -------------------------------------- |
| awaiting\_funds | Waiting for sender to deposit funds        | Provide deposit instructions to sender |
| funds\_received | Funds detected, processing conversion      | Wait for completion                    |
| processing      | Converting and transferring to destination | Monitor for completion                 |
| completed       | Transfer successful                        | Check receipt for final amounts        |
| failed          | Transfer failed                            | Check failure reason, may need retry   |

## Example Requests

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.devdraft.ai/api/v0/transfers/direct-wallet" \
    -H "Content-Type: application/json" \
    -H "x-client-key: your_client_key_here" \
    -H "x-client-secret: your_client_secret_here" \
    -d '{
      "walletId": "550e8400-e29b-41d4-a716-446655440000",
      "network": "solana", 
      "stableCoinCurrency": "usdc",
      "amount": 1000.50
    }'
  ```

  ```javascript JavaScript theme={null}
  const transferData = {
    walletId: '550e8400-e29b-41d4-a716-446655440000',
    network: 'solana',
    stableCoinCurrency: 'usdc',
    amount: 1000.50
  };

  const response = await fetch('https://api.devdraft.ai/api/v0/transfers/direct-wallet', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-client-key': 'your_client_key_here',
      'x-client-secret': 'your_client_secret_here'
    },
    body: JSON.stringify(transferData)
  });

  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  const transfer = await response.json();

  // Extract deposit instructions for the sender
  const instructions = transfer.source_deposit_instructions;
  console.log('Sender should send', instructions.amount, instructions.currency);
  console.log('To address:', instructions.to_address);
  console.log('Include memo:', instructions.deposit_message);
  ```

  ```python Python theme={null}
  import requests
  import json

  url = "https://api.devdraft.ai/api/v0/transfers/direct-wallet"
  headers = {
      'Content-Type': 'application/json',
      'x-client-key': 'your_client_key_here',
      'x-client-secret': 'your_client_secret_here'
  }

  data = {
      'walletId': '550e8400-e29b-41d4-a716-446655440000',
      'network': 'solana',
      'stableCoinCurrency': 'usdc', 
      'amount': 1000.50
  }

  response = requests.post(url, headers=headers, data=json.dumps(data))

  if response.status_code == 201:
      transfer = response.json()
      instructions = transfer['source_deposit_instructions']
      
      print(f"Sender should send {instructions['amount']} {instructions['currency']}")
      print(f"To address: {instructions['to_address']}")
      print(f"Include memo: {instructions['deposit_message']}")
  else:
      print(f"Error: {response.status_code}")
      print(response.text)
  ```

  ```php PHP theme={null}
  <?php
  $data = [
      'walletId' => '550e8400-e29b-41d4-a716-446655440000',
      'network' => 'solana',
      'stableCoinCurrency' => 'usdc',
      'amount' => 1000.50
  ];

  $curl = curl_init();

  curl_setopt_array($curl, [
      CURLOPT_URL => 'https://api.devdraft.ai/api/v0/transfers/direct-wallet',
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_POST => true,
      CURLOPT_POSTFIELDS => json_encode($data),
      CURLOPT_HTTPHEADER => [
          'Content-Type: application/json',
          'x-client-key: your_client_key_here',
          'x-client-secret: your_client_secret_here'
      ],
  ]);

  $response = curl_exec($curl);
  $httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
  curl_close($curl);

  if ($httpCode === 201) {
      $transfer = json_decode($response, true);
      $instructions = $transfer['source_deposit_instructions'];
      
      echo "Sender should send {$instructions['amount']} {$instructions['currency']}\n";
      echo "To address: {$instructions['to_address']}\n";
      echo "Include memo: {$instructions['deposit_message']}\n";
  } else {
      echo "Error: $httpCode\n";
      echo $response;
  }
  ?>
  ```
</CodeGroup>

## Error Responses

<CodeGroup>
  ```json 400 Bad Request theme={null}
  {
    "statusCode": 400,
    "message": "Invalid network or currency combination",
    "error": "Bad Request"
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "statusCode": 404,
    "message": "Devdraft wallet not found with ID: 550e8400-e29b-41d4-a716-446655440000",
    "error": "Not Found"
  }
  ```

  ```json 422 Unprocessable Entity theme={null}
  {
    "statusCode": 422,
    "message": "EURC is only supported on Solana network",
    "error": "Unprocessable Entity"
  }
  ```
</CodeGroup>

## Important Notes

<AccordionGroup>
  <Accordion title="Developer Fees" icon="dollar-sign">
    * **0.8% developer fee** is automatically applied to all transfers
    * Fee is calculated on the total transfer amount
    * Fee is deducted from the final amount received
  </Accordion>

  <Accordion title="Flexible vs Fixed Amount" icon="arrows-up-down">
    * **With amount**: Creates fixed amount transfer with specific deposit instructions
    * **Without amount**: Creates flexible amount transfer allowing variable amounts
  </Accordion>

  <Accordion title="Network Compatibility" icon="network-wired">
    * **EURC** is currently only supported on **Solana** network
    * **USDC** is supported on all networks
    * Cross-network transfers are automatically handled
  </Accordion>

  <Accordion title="Security & Monitoring" icon="shield">
    * All transfers are monitored in real-time
    * Deposit instructions expire after a set period
    * Failed transfers can be retried or refunded
  </Accordion>
</AccordionGroup>

## Use Cases

<CardGroup cols={2}>
  <Card title="Customer Deposits" icon="wallet">
    Allow customers to deposit from their external wallets
  </Card>

  <Card title="Cross-Platform Integration" icon="arrows-turn-right">
    Accept funds from other platforms/exchanges
  </Card>

  <Card title="B2B Payments" icon="handshake">
    Receive payments from business partners
  </Card>

  <Card title="Remittances" icon="globe">
    International money transfers via stablecoins
  </Card>

  <Card title="DeFi Integration" icon="coins">
    Receive funds from DeFi protocols
  </Card>
</CardGroup>

## Next Steps

After creating a direct wallet transfer:

<Steps>
  <Step title="Provide Instructions">
    Share `source_deposit_instructions` with the sender
  </Step>

  <Step title="Monitor Status">
    Poll transfer status or use webhooks for updates
  </Step>

  <Step title="Handle Completion">
    Process successful transfers in your application
  </Step>

  <Step title="Error Handling">
    Implement retry logic for failed transfers
  </Step>
</Steps>

## Related Endpoints

* `GET /api/v0/wallets` - List your Devdraft wallets
* `GET /api/v0/transfers/{id}` - Check transfer status
* `POST /api/v0/transfers/direct-bank` - Create bank-to-wallet transfer