Transfer Stablecoin

Transfer stablecoins between addresses with optional batch support

POST /v1/stablecoin/transfer

Transfer Stablecoin

cURL

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>"
}
'

Single Transfer Request

{
  "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 address

Example: stateset1qypqxpq9qcrsszg2pvxq6rs0zqg3yyc5lzv7xu

to · string · required

The recipient’s blockchain address

amount · object · required

The transfer amount

Show Amount Object

denom · string · required

The stablecoin denomination (e.g., “ssusd”)

amount · string · required

The amount in smallest unit (e.g., “1000000” for 1 ssUSD)

Batch Transfer

from · string · required

The sender’s blockchain address for all transfers

transfers · array · required

Array of transfer objects

Show Transfer Object

to · string · required

Recipient address

amount · object · required

Transfer amount (same structure as single transfer)

memo · string

Optional memo for this transfer

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)

Show Transfer Details

from · string

Sender address

to · string

Recipient address

amount · object

Transfer amount with display formatting

status · string

Individual transfer status

total_amount · object

Total amount transferred (for batch)

fees · object

Fee breakdown

Show Fees Object

network_fee · string

Blockchain network fee

priority_fee · string

Additional priority fee (if applicable)

total_fee · string

Total fees in USD

block_height · integer

Block height of confirmation

created_at · string

ISO 8601 timestamp

confirmed_at · string

ISO 8601 timestamp of confirmation

Single Transfer Request

{
  "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

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

Node.js

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