API — Transactions

The transactions endpoint returns on-chain activity for all wallets in your organisation. Results are scoped to your organisation — you will never see transactions from other accounts.

List transactions

bash

GET /api/transactions

curl "https://api.opsion.xyz/api/transactions?pageSize=10" \
  -H "Authorization: Bearer opsk_your_key_here"

Query parameters

Parameter	Type	Description
`walletId`	`uuid`	Filter to a specific wallet ID
`chain`	`string`	Filter by chain identifier (e.g. ethereum)
`direction`	`string`	inbound \| outbound \| internal
`tokenSymbol`	`string`	Filter by token symbol (e.g. ETH, USDC)
`from`	`ISO 8601`	Start of time range (inclusive)
`to`	`ISO 8601`	End of time range (inclusive)
`page`	`number`	Page number, default 1
`pageSize`	`number`	Results per page, 1–100, default 25

bash

# Inbound ETH transfers on Ethereum in January 2025
curl "https://api.opsion.xyz/api/transactions?direction=inbound&tokenSymbol=ETH&from=2025-01-01T00:00:00Z&to=2025-01-31T23:59:59Z" \
  -H "Authorization: Bearer opsk_your_key_here"

Response shape

json

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "hash": "0xabc123…",
      "chain": "ethereum",
      "blockNumber": 21843200,
      "blockTimestamp": "2025-03-21T14:22:59Z",
      "direction": "outbound",
      "txType": "transfer",
      "fromAddress": "0xd8dA6BF…",
      "toAddress": "0xA0b869…",
      "tokenSymbol": "ETH",
      "tokenAmount": "12.5",
      "valueUsd": "37500.00",
      "methodName": null,
      "wallet": {
        "label": "Treasury",
        "type": "eoa",
        "color": "#6366f1"
      }
    }
  ],
  "meta": {
    "total": 1842,
    "page": 1,
    "pageSize": 25
  }
}

Look up a transaction hash

Resolve any transaction hash directly from the blockchain without importing it first. Supports EVM chains, Solana, and XRP Ledger — the correct chain is detected automatically from the hash format.

bash

GET /api/transactions/lookup?hash=<tx_hash>

# EVM (0x + 64 hex chars)
curl "https://api.opsion.xyz/api/transactions/lookup?hash=0xabc123…" \
  -H "Authorization: Bearer opsk_your_key_here"

# Solana (base58, 87–88 chars)
curl "https://api.opsion.xyz/api/transactions/lookup?hash=5wHu…" \
  -H "Authorization: Bearer opsk_your_key_here"

# XRP Ledger (64 uppercase hex chars)
curl "https://api.opsion.xyz/api/transactions/lookup?hash=C53ECF…" \
  -H "Authorization: Bearer opsk_your_key_here"

If the hash is already in your workspace, the response includes "source": "database"and the full stored record. If it's found on-chain, the response has "source": "blockchain"and the decoded transaction data ready to import.

Import a transaction

Manually import any historical transaction into your workspace. Works with EVM, Solana, and XRP Ledger transactions. The simplest flow is to call /lookup first to get the decoded data, then pass it to /import with a walletId.

✦

In-app import

In the console, open the global search (⌘K) and paste any transaction hash — EVM, Solana, or XRPL. The lookup runs automatically and a save dialog lets you associate the transaction with one of your monitored wallets.

bash

POST /api/transactions/import

# Import an EVM transaction
curl -X POST https://api.opsion.xyz/api/transactions/import \
  -H "Authorization: Bearer opsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "walletId": "550e8400-e29b-41d4-a716-446655440000",
    "hash": "0xabc123…",
    "chain": "ethereum",
    "blockNumber": 21843200,
    "blockTimestamp": "2025-03-21T14:22:59Z",
    "fromAddress": "0xd8dA6BF…",
    "toAddress": "0xA0b869…",
    "valueDecimal": "1.5",
    "txType": "transfer",
    "status": "success"
  }'

# Import a Solana transaction
curl -X POST https://api.opsion.xyz/api/transactions/import \
  -H "Authorization: Bearer opsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "walletId": "550e8400-e29b-41d4-a716-446655440001",
    "hash": "5wHu1234…",
    "chain": "solana",
    "blockNumber": 280000000,
    "blockTimestamp": "2025-03-21T14:22:59Z",
    "fromAddress": "7xKXtg2CW87…",
    "toAddress": "4vJ9JU1bJJE…",
    "valueDecimal": "2.5",
    "txType": "transfer",
    "status": "success"
  }'

Field	Type	Required	Description
`walletId`	`uuid`	Yes	ID of the wallet to associate this transaction with
`hash`	`string`	Yes	EVM (0x…), Solana (base58), or XRPL (64 hex) hash
`chain`	`string`	Yes	Chain identifier — e.g. ethereum, solana, xrp
`blockNumber`	`integer`	Yes	Block number or Solana slot
`blockTimestamp`	`string`	Yes	ISO 8601 timestamp of the block
`fromAddress`	`string`	Yes	Sender address
`toAddress`	`string`	No	Recipient address (omit for contract deploys)
`valueDecimal`	`string`	No	Human-readable amount (e.g. "1.5" for 1.5 ETH or SOL)
`tokenSymbol`	`string`	No	Token symbol for SPL/ERC-20 transfers (e.g. USDC)
`txType`	`string`	No	transfer \| contract_call \| contract_deploy (default: transfer)
`status`	`string`	No	success \| failed (default: success)

Returns 201 Created with the transaction object. If the hash + wallet combination already exists, returns 200 OK with the existing record and an "alreadyExists": true flag — no duplicate is created.

Annotate a transaction

Add internal notes or tags to any transaction for audit and review purposes.

bash

PATCH /api/transactions/:id/annotate

curl -X PATCH https://api.opsion.xyz/api/transactions/550e8400-e29b-41d4-a716-446655440001/annotate \
  -H "Authorization: Bearer opsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "notes": "Approved by CFO on 2025-03-21",
    "tags": ["approved", "q1-2025"]
  }'

Export CSV

Download a filtered transaction set as CSV for spreadsheet analysis or compliance reporting.

bash

GET /api/transactions/export

curl "https://api.opsion.xyz/api/transactions/export?direction=outbound&from=2025-01-01T00:00:00Z" \
  -H "Authorization: Bearer opsk_your_key_here" \
  -o transactions.csv