POST
/
v1
/
stablecoin
/
transfer
Transfer Stablecoin
curl --request POST \
  --url https://api.stateset.com/v1/stablecoin/transfer \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "from": "<string>",
  "to": "<string>",
  "amount": {
    "denom": "<string>",
    "amount": "<string>"
  },
  "transfers": [
    {
      "to": "<string>",
      "amount": {},
      "memo": "<string>"
    }
  ],
  "memo": "<string>",
  "priority": "<string>",
  "idempotency_key": "<string>",
  "metadata": {},
  "scheduled_at": "<string>"
}'
{
  "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"
  }
}
This endpoint enables instant stablecoin transfers between addresses on the StateSet network. Supports both single and batch transfers with atomic execution.

​
Authentication

This endpoint requires a valid API key with stablecoin:transfer permissions. 
Authorization: Bearer YOUR_API_KEY

​
Request Body

​
Single Transfer

​
from
string
required
The sender’s blockchain addressExample: stateset1qypqxpq9qcrsszg2pvxq6rs0zqg3yyc5lzv7xu
​
to
string
required
The recipient’s blockchain address
​
amount
object
required
The transfer amount

​
Batch Transfer

​
from
string
required
The sender’s blockchain address for all transfers
​
transfers
array
required
Array of transfer objects

​
Common Fields

​
memo
string
Optional memo for the transaction
​
priority
string
Transaction priority: “low”, “medium”, “high” (affects gas price)Default: “medium”
​
idempotency_key
string
Unique key to prevent duplicate transfers
​
metadata
object
Additional metadata for the transfer
​
scheduled_at
string
ISO 8601 timestamp for scheduled transfers (future feature)

​
Response

​
id
string
Unique transfer identifier
​
object
string
Object type: “transfer” or “batch_transfer”
​
transaction_hash
string
Blockchain transaction hash
​
status
string
Transfer status: “pending”, “confirmed”, “failed”
​
transfers
array
Array of individual transfers (for batch transfers)
​
total_amount
object
Total amount transferred (for batch)
​
fees
object
Fee breakdown
​
block_height
integer
Block height of confirmation
​
created_at
string
ISO 8601 timestamp
​
confirmed_at
string
ISO 8601 timestamp of confirmation
{
  "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"
  }
}

​
Error Codes

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

​
Transfer Limits

TypeLimitDescription
Single Transfer$10,000,000Per transaction
Batch Transfers100Maximum recipients per batch
Daily Volume$50,000,000Per account
Minimum Amount$0.01Minimum 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

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);
  }
}