# 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`, `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)
* `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**    | `UsdPurchase`, `UsdcPurchase`, `Purchase`, `Redeem`, `Burn`, `ProtocolMint`, `ProtocolRedeem`, `MintRequest`, `RedemptionRequest`                                     |
| **Equities** | `Issuance`, `Vest`, `Unlock`, `Release`, `Lockup`, `TaTransfer`, `BookEntryTransfer`, `BookEntryBuyback`, `DipPurchase`, `OnchainDeFiLpIssuance`, `OnchainDeFiLpBurn` |

**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 purchases in Q4 2024:**

```
GET /v2/transactions?transaction_status=Completed&transaction_type=Purchase,UsdcPurchase&from_timestamp=2024-10-01T00:00:00Z&until_timestamp=2024-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).

```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": "0x...",
    "source_details": {
      "chain_id": 1,
      "chain_name": "ethereum",
      "transaction_hash": "0x..."
    },
    ...
  }
]
```

#### Error responses

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.superstate.com/investors/api/transactions-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.