> ## 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.

# List Stablecoin Transactions

> Retrieve stablecoin transaction history with filtering and pagination

<Note>
  This endpoint provides a comprehensive view of stablecoin transactions including issuances, redemptions, transfers, and burns.
</Note>

## Authentication

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

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

## Query Parameters

<ParamField query="address" type="string">
  Filter transactions by address (as sender or recipient)
</ParamField>

<ParamField query="type" type="string">
  Filter by transaction type: "issue", "redeem", "transfer", "burn"
</ParamField>

<ParamField query="status" type="string">
  Filter by status: "pending", "confirmed", "failed"
</ParamField>

<ParamField query="denom" type="string">
  Filter by stablecoin denomination (e.g., "ssusd")
</ParamField>

<ParamField query="start_date" type="string">
  Start date for transaction range (ISO 8601 format)
</ParamField>

<ParamField query="end_date" type="string">
  End date for transaction range (ISO 8601 format)
</ParamField>

<ParamField query="min_amount" type="string">
  Minimum transaction amount (in smallest unit)
</ParamField>

<ParamField query="max_amount" type="string">
  Maximum transaction amount (in smallest unit)
</ParamField>

<ParamField query="limit" type="integer">
  Number of results per page (max: 100, default: 20)
</ParamField>

<ParamField query="offset" type="integer">
  Pagination offset
</ParamField>

<ParamField query="order" type="string">
  Sort order: "asc" or "desc" (default: "desc")
</ParamField>

## Response

<ResponseField name="transactions" type="array">
  Array of transaction objects

  <Expandable title="Transaction Object">
    <ResponseField name="id" type="string">
      Unique transaction identifier
    </ResponseField>

    <ResponseField name="type" type="string">
      Transaction type: "issue", "redeem", "transfer", "burn"
    </ResponseField>

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

    <ResponseField name="from" type="string">
      Sender address (null for issuances)
    </ResponseField>

    <ResponseField name="to" type="string">
      Recipient address (null for redemptions/burns)
    </ResponseField>

    <ResponseField name="amount" type="object">
      Transaction amount details

      <Expandable title="Amount Object">
        <ResponseField name="denom" type="string">
          Stablecoin denomination
        </ResponseField>

        <ResponseField name="amount" type="string">
          Amount in smallest unit
        </ResponseField>

        <ResponseField name="display_amount" type="string">
          Human-readable amount
        </ResponseField>

        <ResponseField name="usd_value" type="string">
          USD equivalent at time of transaction
        </ResponseField>
      </Expandable>
    </ResponseField>

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

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

        <ResponseField name="processing_fee" type="string">
          Processing fee (for issuance/redemption)
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="status" type="string">
      Transaction status
    </ResponseField>

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

    <ResponseField name="memo" type="string">
      Transaction memo/note
    </ResponseField>

    <ResponseField name="metadata" type="object">
      Additional transaction metadata
    </ResponseField>

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

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

<ResponseField name="pagination" type="object">
  Pagination information

  <Expandable title="Pagination Object">
    <ResponseField name="total" type="integer">
      Total number of transactions
    </ResponseField>

    <ResponseField name="limit" type="integer">
      Results per page
    </ResponseField>

    <ResponseField name="offset" type="integer">
      Current offset
    </ResponseField>

    <ResponseField name="has_more" type="boolean">
      Whether more results are available
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json Example Response theme={null}
  {
    "transactions": [
      {
        "id": "txn_abc123def456",
        "type": "transfer",
        "transaction_hash": "A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0",
        "from": "stateset1qypqxpq9qcrsszg2pvxq6rs0zqg3yyc5lzv7xu",
        "to": "stateset1abcdefghijklmnopqrstuvwxyz123456789012",
        "amount": {
          "denom": "ssusd",
          "amount": "500000000",
          "display_amount": "500.00 ssUSD",
          "usd_value": "500.00"
        },
        "fees": {
          "network_fee": "0.01",
          "processing_fee": "0.00"
        },
        "status": "confirmed",
        "block_height": 1234567,
        "memo": "Payment for invoice #INV-2024-001",
        "metadata": {
          "invoice_id": "inv_123456",
          "order_id": "ord_789012"
        },
        "created_at": "2024-01-15T09:30:00Z",
        "confirmed_at": "2024-01-15T09:30:05Z"
      },
      {
        "id": "txn_xyz789uvw012",
        "type": "issue",
        "transaction_hash": "B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0U1",
        "from": null,
        "to": "stateset1qypqxpq9qcrsszg2pvxq6rs0zqg3yyc5lzv7xu",
        "amount": {
          "denom": "ssusd",
          "amount": "10000000000",
          "display_amount": "10,000.00 ssUSD",
          "usd_value": "10000.00"
        },
        "fees": {
          "network_fee": "0.50",
          "processing_fee": "10.00"
        },
        "status": "confirmed",
        "block_height": 1234500,
        "memo": "Merchant funding",
        "metadata": {
          "reference_id": "ISS-2024-001234",
          "source_type": "bank_wire"
        },
        "created_at": "2024-01-14T14:20:00Z",
        "confirmed_at": "2024-01-14T14:20:10Z"
      }
    ],
    "pagination": {
      "total": 156,
      "limit": 20,
      "offset": 0,
      "has_more": true
    }
  }
  ```
</ResponseExample>

## Error Codes

| Code  | Description                    |
| ----- | ------------------------------ |
| `400` | Invalid query parameters       |
| `401` | Unauthorized - Invalid API key |
| `429` | Rate limit exceeded            |
| `500` | Internal server error          |

## Code Examples

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

  async function getTransactionHistory(params) {
    try {
      const response = await axios.get(
        'https://api.stateset.com/v1/stablecoin/transactions',
        {
          params: {
            address: 'stateset1qypqxpq9qcrsszg2pvxq6rs0zqg3yyc5lzv7xu',
            type: 'transfer',
            denom: 'ssusd',
            start_date: '2024-01-01T00:00:00Z',
            limit: 50,
            order: 'desc'
          },
          headers: {
            'Authorization': 'Bearer YOUR_API_KEY'
          }
        }
      );
      
      console.log(`Found ${response.data.pagination.total} transactions`);
      
      response.data.transactions.forEach(tx => {
        console.log(`${tx.type}: ${tx.amount.display_amount} - ${tx.status}`);
      });
      
      return response.data;
    } catch (error) {
      console.error('Failed to get transactions:', error.response.data);
    }
  }
  ```

  ```python Python theme={null}
  import requests
  from datetime import datetime, timedelta

  def get_transaction_history():
      url = "https://api.stateset.com/v1/stablecoin/transactions"
      
      headers = {
          "Authorization": "Bearer YOUR_API_KEY"
      }
      
      # Get transactions from last 30 days
      end_date = datetime.utcnow()
      start_date = end_date - timedelta(days=30)
      
      params = {
          "address": "stateset1qypqxpq9qcrsszg2pvxq6rs0zqg3yyc5lzv7xu",
          "start_date": start_date.isoformat() + "Z",
          "end_date": end_date.isoformat() + "Z",
          "limit": 100
      }
      
      try:
          response = requests.get(url, headers=headers, params=params)
          response.raise_for_status()
          
          data = response.json()
          
          # Calculate totals by type
          totals = {}
          for tx in data['transactions']:
              tx_type = tx['type']
              amount = float(tx['amount']['usd_value'])
              totals[tx_type] = totals.get(tx_type, 0) + amount
          
          print("Transaction Summary (Last 30 Days):")
          for tx_type, total in totals.items():
              print(f"{tx_type.capitalize()}: ${total:,.2f}")
              
          return data
      except requests.exceptions.RequestException as e:
          print(f"Failed to get transactions: {e}")
  ```

  ```curl cURL theme={null}
  curl -X GET "https://api.stateset.com/v1/stablecoin/transactions?address=stateset1qypqxpq9qcrsszg2pvxq6rs0zqg3yyc5lzv7xu&type=transfer&limit=20" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</CodeGroup>