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

# Transfer Stablecoin

> Transfer stablecoins between addresses with optional batch support

<Note>
  This endpoint enables instant stablecoin transfers between addresses on the StateSet network. Supports both single and batch transfers with atomic execution.
</Note>

## Authentication

This endpoint requires a valid API key with `stablecoin:transfer` permissions.

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Request Body

### Single Transfer

<ParamField body="from" type="string" required>
  The sender's blockchain address

  Example: `stateset1qypqxpq9qcrsszg2pvxq6rs0zqg3yyc5lzv7xu`
</ParamField>

<ParamField body="to" type="string" required>
  The recipient's blockchain address
</ParamField>

<ParamField body="amount" type="object" required>
  The transfer amount

  <Expandable title="Amount Object">
    <ParamField body="denom" type="string" required>
      The stablecoin denomination (e.g., "ssusd")
    </ParamField>

    <ParamField body="amount" type="string" required>
      The amount in smallest unit (e.g., "1000000" for 1 ssUSD)
    </ParamField>
  </Expandable>
</ParamField>

### Batch Transfer

<ParamField body="from" type="string" required>
  The sender's blockchain address for all transfers
</ParamField>

<ParamField body="transfers" type="array" required>
  Array of transfer objects

  <Expandable title="Transfer Object">
    <ParamField body="to" type="string" required>
      Recipient address
    </ParamField>

    <ParamField body="amount" type="object" required>
      Transfer amount (same structure as single transfer)
    </ParamField>

    <ParamField body="memo" type="string">
      Optional memo for this transfer
    </ParamField>
  </Expandable>
</ParamField>

### Common Fields

<ParamField body="memo" type="string">
  Optional memo for the transaction
</ParamField>

<ParamField body="priority" type="string">
  Transaction priority: "low", "medium", "high" (affects gas price)

  Default: "medium"
</ParamField>

<ParamField body="idempotency_key" type="string">
  Unique key to prevent duplicate transfers
</ParamField>

<ParamField body="metadata" type="object">
  Additional metadata for the transfer
</ParamField>

<ParamField body="scheduled_at" type="string">
  ISO 8601 timestamp for scheduled transfers (future feature)
</ParamField>

## Response

<ResponseField name="id" type="string">
  Unique transfer identifier
</ResponseField>

<ResponseField name="object" type="string">
  Object type: "transfer" or "batch\_transfer"
</ResponseField>

<ResponseField name="transaction_hash" type="string">
  Blockchain transaction hash
</ResponseField>

<ResponseField name="status" type="string">
  Transfer status: "pending", "confirmed", "failed"
</ResponseField>

<ResponseField name="transfers" type="array">
  Array of individual transfers (for batch transfers)

  <Expandable title="Transfer Details">
    <ResponseField name="from" type="string">
      Sender address
    </ResponseField>

    <ResponseField name="to" type="string">
      Recipient address
    </ResponseField>

    <ResponseField name="amount" type="object">
      Transfer amount with display formatting
    </ResponseField>

    <ResponseField name="status" type="string">
      Individual transfer status
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total_amount" type="object">
  Total amount transferred (for batch)
</ResponseField>

<ResponseField name="fees" type="object">
  Fee breakdown

  <Expandable title="Fees Object">
    <ResponseField name="network_fee" type="string">
      Blockchain network fee
    </ResponseField>

    <ResponseField name="priority_fee" type="string">
      Additional priority fee (if applicable)
    </ResponseField>

    <ResponseField name="total_fee" type="string">
      Total fees in USD
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="block_height" type="integer">
  Block height of confirmation
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp
</ResponseField>

<ResponseField name="confirmed_at" type="string">
  ISO 8601 timestamp of confirmation
</ResponseField>

<ResponseExample>
  ```json Single Transfer Request theme={null}
  {
    "from": "stateset1qypqxpq9qcrsszg2pvxq6rs0zqg3yyc5lzv7xu",
    "to": "stateset1abcdefghijklmnopqrstuvwxyz123456789012",
    "amount": {
      "denom": "ssusd",
      "amount": "500000000"
    },
    "memo": "Payment for invoice #INV-2024-001",
    "priority": "high",
    "idempotency_key": "transfer_abc123",
    "metadata": {
      "invoice_id": "inv_123456",
      "order_id": "ord_789012"
    }
  }
  ```

  ```json Batch Transfer Request theme={null}
  {
    "from": "stateset1qypqxpq9qcrsszg2pvxq6rs0zqg3yyc5lzv7xu",
    "transfers": [
      {
        "to": "stateset1abcdefghijklmnopqrstuvwxyz123456789012",
        "amount": {
          "denom": "ssusd",
          "amount": "250000000"
        },
        "memo": "Vendor payment A"
      },
      {
        "to": "stateset1zyxwvutsrqponmlkjihgfedcba987654321098",
        "amount": {
          "denom": "ssusd",
          "amount": "750000000"
        },
        "memo": "Vendor payment B"
      }
    ],
    "memo": "Batch vendor payments - Jan 2024",
    "priority": "medium"
  }
  ```

  ```json Example Response theme={null}
  {
    "id": "txf_batch_7h8g9f0e1d2c3b4a",
    "object": "batch_transfer",
    "transaction_hash": "C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0U1V2",
    "status": "confirmed",
    "transfers": [
      {
        "from": "stateset1qypqxpq9qcrsszg2pvxq6rs0zqg3yyc5lzv7xu",
        "to": "stateset1abcdefghijklmnopqrstuvwxyz123456789012",
        "amount": {
          "denom": "ssusd",
          "amount": "250000000",
          "display_amount": "250.00 ssUSD"
        },
        "status": "confirmed"
      },
      {
        "from": "stateset1qypqxpq9qcrsszg2pvxq6rs0zqg3yyc5lzv7xu",
        "to": "stateset1zyxwvutsrqponmlkjihgfedcba987654321098",
        "amount": {
          "denom": "ssusd",
          "amount": "750000000",
          "display_amount": "750.00 ssUSD"
        },
        "status": "confirmed"
      }
    ],
    "total_amount": {
      "denom": "ssusd",
      "amount": "1000000000",
      "display_amount": "1,000.00 ssUSD"
    },
    "fees": {
      "network_fee": "0.02",
      "priority_fee": "0.00",
      "total_fee": "0.02"
    },
    "block_height": 1234568,
    "created_at": "2024-01-15T11:00:00Z",
    "confirmed_at": "2024-01-15T11:00:03Z"
  }
  ```
</ResponseExample>

## Error Codes

| Code  | Description                    |
| ----- | ------------------------------ |
| `400` | Invalid request parameters     |
| `401` | Unauthorized - Invalid API key |
| `403` | Forbidden - Account restricted |
| `422` | Insufficient balance           |
| `429` | Rate limit exceeded            |
| `500` | Internal server error          |

## Transfer Limits

| Type            | Limit        | Description                  |
| --------------- | ------------ | ---------------------------- |
| Single Transfer | \$10,000,000 | Per transaction              |
| Batch Transfers | 100          | Maximum recipients per batch |
| Daily Volume    | \$50,000,000 | Per account                  |
| Minimum Amount  | \$0.01       | Minimum transfer value       |

## Best Practices

1. **Use idempotency keys** to prevent duplicate transfers
2. **Batch transfers** when sending to multiple recipients to save on fees
3. **Set appropriate priority** based on urgency
4. **Include memos** for better transaction tracking
5. **Validate addresses** before initiating transfers

## Code Examples

<CodeGroup>
  ```javascript Node.js theme={null}
  const axios = require('axios');

  // Single transfer
  async function transferStablecoin(to, amount) {
    try {
      const response = await axios.post(
        'https://api.stateset.com/v1/stablecoin/transfer',
        {
          from: 'stateset1qypqxpq9qcrsszg2pvxq6rs0zqg3yyc5lzv7xu',
          to: to,
          amount: {
            denom: 'ssusd',
            amount: amount
          },
          memo: 'Payment transfer',
          idempotency_key: `transfer_${Date.now()}`
        },
        {
          headers: {
            'Authorization': 'Bearer YOUR_API_KEY',
            'Content-Type': 'application/json'
          }
        }
      );
      
      console.log('Transfer successful:', response.data);
      return response.data;
    } catch (error) {
      console.error('Transfer failed:', error.response.data);
    }
  }

  // Batch transfer
  async function batchTransfer(recipients) {
    try {
      const transfers = recipients.map(r => ({
        to: r.address,
        amount: {
          denom: 'ssusd',
          amount: r.amount
        },
        memo: r.memo
      }));
      
      const response = await axios.post(
        'https://api.stateset.com/v1/stablecoin/transfer',
        {
          from: 'stateset1qypqxpq9qcrsszg2pvxq6rs0zqg3yyc5lzv7xu',
          transfers: transfers,
          memo: 'Batch payment processing'
        },
        {
          headers: {
            'Authorization': 'Bearer YOUR_API_KEY',
            'Content-Type': 'application/json'
          }
        }
      );
      
      console.log(`Transferred to ${transfers.length} recipients`);
      return response.data;
    } catch (error) {
      console.error('Batch transfer failed:', error.response.data);
    }
  }
  ```

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

  class StablecoinTransfer:
      def __init__(self, api_key):
          self.api_key = api_key
          self.base_url = "https://api.stateset.com/v1/stablecoin"
          
      def single_transfer(self, from_address, to_address, amount, memo=None):
          """Execute a single stablecoin transfer"""
          url = f"{self.base_url}/transfer"
          
          headers = {
              "Authorization": f"Bearer {self.api_key}",
              "Content-Type": "application/json"
          }
          
          data = {
              "from": from_address,
              "to": to_address,
              "amount": {
                  "denom": "ssusd",
                  "amount": str(amount)
              },
              "idempotency_key": str(uuid.uuid4())
          }
          
          if memo:
              data["memo"] = memo
              
          try:
              response = requests.post(url, json=data, headers=headers)
              response.raise_for_status()
              return response.json()
          except requests.exceptions.RequestException as e:
              print(f"Transfer failed: {e}")
              return None
              
      def batch_transfer(self, from_address, recipients):
          """Execute batch transfer to multiple recipients"""
          url = f"{self.base_url}/transfer"
          
          headers = {
              "Authorization": f"Bearer {self.api_key}",
              "Content-Type": "application/json"
          }
          
          transfers = []
          for recipient in recipients:
              transfers.append({
                  "to": recipient["address"],
                  "amount": {
                      "denom": "ssusd",
                      "amount": str(recipient["amount"])
                  },
                  "memo": recipient.get("memo", "")
              })
              
          data = {
              "from": from_address,
              "transfers": transfers,
              "memo": "Batch transfer"
          }
          
          try:
              response = requests.post(url, json=data, headers=headers)
              response.raise_for_status()
              result = response.json()
              
              print(f"Batch transfer completed: {len(transfers)} recipients")
              print(f"Total amount: {result['total_amount']['display_amount']}")
              
              return result
          except requests.exceptions.RequestException as e:
              print(f"Batch transfer failed: {e}")
              return None

  # Example usage
  transfer = StablecoinTransfer("YOUR_API_KEY")

  # Single transfer
  transfer.single_transfer(
      "stateset1qypqxpq9qcrsszg2pvxq6rs0zqg3yyc5lzv7xu",
      "stateset1abcdefghijklmnopqrstuvwxyz123456789012",
      1000000000,  # 1000 ssUSD
      "Invoice payment"
  )

  # Batch transfer
  recipients = [
      {"address": "stateset1abc...", "amount": 500000000, "memo": "Vendor A"},
      {"address": "stateset1xyz...", "amount": 300000000, "memo": "Vendor B"}
  ]
  transfer.batch_transfer(
      "stateset1qypqxpq9qcrsszg2pvxq6rs0zqg3yyc5lzv7xu",
      recipients
  )
  ```
</CodeGroup>