> For the complete documentation index, see [llms.txt](https://docs.superstate.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.superstate.com/investors/api/transactions-api.md).

# Transactions API

This document describes the available query parameters for filtering transactions via the `/v2/transactions` endpoint. 

***

## Authentication

This endpoint requires API key authentication with the `TransactionViewer` role. Contact Superstate for an API key. 

***

## Sending a request

For information on how to send a request, please see the [API key section on the API page](/investors/api.md#using-api-key-authenticated-endpoints).

#### Example

```typescript
import { superstateApiKeyRequest, TransactionStatus } from '@superstateinc/api-key-request';

const transactions = await superstateApiKeyRequest({
  apiKey: SUPERSTATE_API_KEY,
  apiSecret: SUPERSTATE_API_SECRET,
  endpoint: "/v2/transactions",
  method: "GET",
  queryParams: {
    from_timestamp: "2024-10-01T00:00:00Z",
    transaction_status: TransactionStatus.Pending,
    transaction_type: "Purchase,Redeem",
  },
});

console.log(transactions);
```

***

## Query parameters

#### transaction\_status

Filter transactions by their current status.

| Property       | Value                                                 |
| -------------- | ----------------------------------------------------- |
| Type           | `string`                                              |
| Required       | No                                                    |
| Allowed Values | `Pending`, `PaymentPending`, `Processed`, `Completed` |

**Status Descriptions:**

* `Pending` - Transaction has been initiated but not yet completed
* `PaymentPending` - Payment has been initiated (e.g., USDC transfer) but awaiting confirmation (approximately 12 blocks)
* `Processed` — processing has occurred but the transaction is not yet complete.
* `Completed` - Transaction has been fully processed

**Example:**

```
GET /v2/transactions?transaction_status=Completed
```

#### transaction\_type

Filter transactions by one or more transaction types. Multiple types can be specified as a comma-separated list.

| Property | Value                           |
| -------- | ------------------------------- |
| Type     | `string` (comma-separated list) |
| Required | No                              |

**Important:** Comma-separated values must NOT contain spaces, otherwise HMAC signatures will not match.

**Allowed Values:**

| Category     | Types                                                                                                                                                                 |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **General**  | `OnchainTransfer`, `Tokenize`, `Bridge`, `ProtocolTransfer`, `AdminAdjustment`                                                                                        |
| **Funds**    | `Purchase`, `Redeem`, `Burn`, `ProtocolMint`, `ProtocolRedeem`, `MintRequest`, `UsdPurchase`, `UsdcPurchase`, `RedemptionRequest`                                     |
| **Equities** | `Issuance`, `Vest`, `Unlock`, `Release`, `Lockup`, `TaTransfer`, `BookEntryTransfer`, `BookEntryBuyback`, `DipPurchase`, `OnchainDeFiLpIssuance`, `OnchainDeFiLpBurn` |

> **NOTE:** `UsdPurchase` and `UsdcPurchase` represent temporary inbound-payment records, not completed subscriptions. Once a payment is allocated to a subscription, that payment row is removed. To detect completed subscriptions, filter for `transaction_type=Purchase` and `transaction_status=Completed`. USTB realtime subscriptions do not emit a `UsdPurchase` row.

**Example:**

```
GET /v2/transactions?transaction_type=Purchase,Redeem
```

#### from\_timestamp

Filter transactions created on or after this UTC timestamp.

| Property | Value                        |
| -------- | ---------------------------- |
| Type     | `string` (ISO 8601 datetime) |
| Required | No                           |

**Example:**

```
GET /v2/transactions?from_timestamp=2024-01-01T00:00:00Z
```

#### until\_timestamp

Filter transactions created on or before this UTC timestamp.

| Property | Value                        |
| -------- | ---------------------------- |
| Type     | `string` (ISO 8601 datetime) |
| Required | No                           |

**Example:**

```
GET /v2/transactions?until_timestamp=2024-12-31T23:59:59Z
```

#### from\_price\_timestamp

Filter transactions with a price timestamp on or after this UTC timestamp.

| Property | Value                        |
| -------- | ---------------------------- |
| Type     | `string` (ISO 8601 datetime) |
| Required | No                           |

**Note:** Only transactions that have a `price_timestamp` value will be included when this filter is applied.

**Example:**

```
GET /v2/transactions?from_price_timestamp=2024-06-01T00:00:00Z
```

#### until\_price\_timestamp

Filter transactions with a price timestamp on or before this UTC timestamp.

| Property | Value                        |
| -------- | ---------------------------- |
| Type     | `string` (ISO 8601 datetime) |
| Required | No                           |

**Note:** Only transactions that have a `price_timestamp` value will be included when this filter is applied.

**Example:**

```
GET /v2/transactions?until_price_timestamp=2024-06-30T23:59:59Z
```

#### transaction\_hash

Filter transactions by a specific blockchain transaction hash.

| Property | Value    |
| -------- | -------- |
| Type     | `string` |
| Required | No       |

**Example:**

```
GET /v2/transactions?transaction_hash=0x1234567890abcdef...
```

#### from\_address

Filter transactions by the source/sender blockchain address.

| Property | Value                         |
| -------- | ----------------------------- |
| Type     | `string` (blockchain address) |
| Required | No                            |

**Example:**

```
GET /v2/transactions?from_address=0xabc123...
```

#### to\_address

Filter transactions by the destination/recipient blockchain address.

| Property | Value                         |
| -------- | ----------------------------- |
| Type     | `string` (blockchain address) |
| Required | No                            |

**Example**

```
GET /v2/transactions?to_address=0xdef456...
```

#### source\_chain\_id

Filter transactions by the source blockchain chain ID.

| Property | Value     |
| -------- | --------- |
| Type     | `integer` |
| Required | No        |

**Common Chain IDs:**

* `1` - Ethereum Mainnet
* `11155111` - Ethereum Sepolia
* `98866` - Plume Mainnet
* `98867` - Plume Testnet
* `900` - Solana MainnetBeta (internal representation chain ID)
* `901` - Solana Devnet (internal representation chain ID)

**Example:**

```
GET /v2/transactions?source_chain_id=1
```

#### destination\_chain\_id

Filter transactions by the destination blockchain chain ID.

| Property | Value     |
| -------- | --------- |
| Type     | `integer` |
| Required | No        |

**Example:**

```
GET /v2/transactions?destination_chain_id=11155111
```

#### source\_chain\_name

Filter transactions by the source blockchain name.

| Property | Value    |
| -------- | -------- |
| Type     | `string` |
| Required | No       |

**Example:**

```
GET /v2/transactions?source_chain_name=ethereum
```

#### destination\_chain\_name

Filter transactions by the destination blockchain name.

| Property | Value    |
| -------- | -------- |
| Type     | `string` |
| Required | No       |

**Example:**

```
GET /v2/transactions?destination_chain_name=sepolia
```

#### dip\_market\_id

Filter transactions by a specific DIP (Direct Issuance Program) market ID.

| Property | Value           |
| -------- | --------------- |
| Type     | `string` (UUID) |
| Required | No              |

**Example:**

```
GET /v2/transactions?dip_market_id=550e8400-e29b-41d4-a716-446655440000
```

#### entity\_id

Filter transactions to only those associated with a specific entity.

| Property | Value     |
| -------- | --------- |
| Type     | `integer` |
| Required | No        |

**Note:** This filter is applied within the scope of the API key's permissions. An organization-scoped API key can filter by any entity within that organization.

**Example:**

```
GET /v2/transactions?entity_id=12345
```

#### subaccount\_id

Filter transactions to only those associated with a specific subaccount.

| Property | Value     |
| -------- | --------- |
| Type     | `integer` |
| Required | No        |

**Example:**

```
GET /v2/transactions?subaccount_id=67890
```

***

## Combining filters

Multiple filters can be combined in a single request. All filters are applied using AND logic.

**Example - Get all completed purchase and redeems in Q4 2025:**

```
GET /v2/transactions?transaction_status=Completed&transaction_type=Purchase,Redeem&from_timestamp=2025-10-01T00:00:00Z&until_timestamp=2025-12-31T23:59:59Z
```

**Example - Get transactions for a specific entity on Ethereum:**

```
GET /v2/transactions?entity_id=123&source_chain_id=1
```

***

## Response

Returns an array of `TransactionV2` objects sorted by `created_at` in descending order (newest first).

**Completed on-chain subscriptions**

For a standard USD subscription delivered on-chain:

* The completed subscription record has `operation_type: "Purchase"` and `status: "Completed"`.
* Use `source_details.transaction_hash` as the on-chain USTB mint transaction hash.
* `destination_details` and `to_address` are `null` for this transaction shape.
* The receiving Ethereum address is returned in `from_address` and `source_details.contract_address`.
* `share_amount` is the amount of USTB issued.
* `dollar_amount` is the subscription notional, calculated from the issued shares and subscription price. It is not a separately reconciled wire-settlement field.

```json
[
  {
    "entity_id": 123,
    "entity_name": "Example Corp",
    "ticker": "USTB",
    "instrument_domain": "Funds",
    "operation_type": "Purchase",
    "status": "Completed",
    "share_amount": "1000.00",
    "dollar_amount": "10000.00",
    "created_at": "2024-12-01T12:00:00Z",
    "completed_at": "2024-12-01T12:05:00Z",
    "from_address": "0x...",
    "to_address": null,
    "source_details": {
      "chain_id": 1,
      "chain_name": "ethereum",
      "contract_address": "0x...",
      "transaction_hash": "0x..."
    },
    "destination_details": null
    ...
  }
]
```

#### Error responses

| Status Code | Description                               |
| ----------- | ----------------------------------------- |
| 400         | Invalid request parameters                |
| 401         | Unauthorized - invalid or missing API key |
| 500         | Internal server error                     |