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.

Example

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

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