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

# Transactions

Endpoints for querying bridge transaction history and status.

## List Transactions

Get bridge transactions with optional filtering and pagination.

```
GET /api/v1/transactions
```

### Query Parameters

| Name        | Type    | Default | Description                                                     |
| ----------- | ------- | ------- | --------------------------------------------------------------- |
| `page`      | integer | 1       | Page number                                                     |
| `limit`     | integer | 50      | Items per page (max 100)                                        |
| `direction` | string  | -       | Filter: `eth2casper` or `casper2eth`                            |
| `status`    | string  | -       | Filter by transaction status                                    |
| `token`     | integer | -       | Filter by token ID                                              |
| `address`   | string  | -       | Filter by sender OR recipient address (EVM `0x...` format only) |
| `sender`    | string  | -       | Filter by sender address only (EVM `0x...` format only)         |
| `recipient` | string  | -       | Filter by recipient address only (EVM `0x...` format only)      |

> **Note:** The `address` parameter matches transactions where the given address appears as either sender or recipient. Use `sender` or `recipient` for more specific filtering. These query filters validate against the EVM address format (`0x` + 40 hex chars, case-insensitive) and reject other formats with a 400. To look up transactions for a **Casper** account or any non-EVM identifier, use the [`/transactions/address/{address}`](#get-transactions-by-address) path endpoint instead.

### Status Values

| Status       | Description                                                                                                                                                                                      |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `confirming` | Source event seen in the unfinalized head window (EVM pre-finality visibility; pruned on reorg)                                                                                                  |
| `finalized`  | Source finality proven — indexer-written. EVM rows reach it via the finalized scan; Casper rows are born here (instant finality, CSPR.cloud streams executed deploys only)                       |
| `attesting`  | Relayers collecting signatures (reserved: not currently written — relayer progress reporting is out of scope while the CLI is under audit)                                                       |
| `submitted`  | Transaction submitted to destination (reserved, as above)                                                                                                                                        |
| `completed`  | Destination transaction indexed. Completion also settles `signaturesCollected = signaturesRequired`: the destination tx can only exist because the locker verified the M-of-N threshold on-chain |
| `failed`     | Transaction failed                                                                                                                                                                               |
| `detected`   | **Legacy** (pre-2026-07): rows created before granular status reporting. The finalized scan upgrades these to `finalized` on re-encounter; treat as equivalent to `finalized`                    |

`signaturesRequired` is read from the locker's `getRelayerSet()` threshold at indexer start (previously hardcoded to 3).

### Response

```json
{
  "success": true,
  "data": [
    {
      "id": 123,
      "txType": "lock",
      "direction": "eth2casper",
      "evmChainId": 11155111,
      "evmChainName": "Ethereum Sepolia",
      "sourceChain": "ethereum",
      "sourceTxHash": "0xabc123...",
      "sourceBlock": 5000000,
      "sourceTimestamp": "2024-01-15T12:30:00Z",
      "destinationChain": "casper",
      "destinationTxHash": "abc123def456...",
      "amount": "10000000",
      "sender": "0x1234...5678",
      "recipient": "01abc...def",
      "status": "completed",
      "signaturesCollected": 3,
      "signaturesRequired": 3,
      "createdAt": "2024-01-15T12:30:00Z",
      "explorerLinks": {
        "source": {
          "url": "https://sepolia.etherscan.io/tx/0xabc123...",
          "explorerName": "Ethereum Sepolia"
        },
        "destination": {
          "url": "https://testnet.cspr.live/deploy/abc123def456...",
          "explorerName": "CSPR Live (Testnet)"
        }
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}
```

### Examples

**Get all completed transactions:**

```bash
curl "https://api.csprbridge.com/api/v1/transactions?status=completed"
```

**Get EVM→Casper transactions:**

```bash
curl "https://api.csprbridge.com/api/v1/transactions?direction=eth2casper"
```

**Get transactions for a specific address (sender or recipient):**

```bash
# EVM address (query filter — EVM format only)
curl "https://api.csprbridge.com/api/v1/transactions?address=0x1234567890abcdef1234567890abcdef12345678"

# Casper account or any other identifier — use the path endpoint
curl "https://api.csprbridge.com/api/v1/transactions/address/01abc123def456..."
```

**Filter by sender only:**

```bash
curl "https://api.csprbridge.com/api/v1/transactions?sender=0x1234567890abcdef1234567890abcdef12345678"
```

**Filter by recipient only:**

```bash
curl "https://api.csprbridge.com/api/v1/transactions?recipient=0x1234567890abcdef1234567890abcdef12345678"
```

**Paginate through results:**

```bash
curl "https://api.csprbridge.com/api/v1/transactions?page=2&limit=50"
```

***

## Get Transaction by ID

Get a specific transaction by its numeric database ID.

```
GET /api/v1/transactions/{id}
```

### Parameters

| Name | In   | Type    | Required | Description             |
| ---- | ---- | ------- | -------- | ----------------------- |
| `id` | path | integer | yes      | Transaction database ID |

### Response

Same format as individual transaction in list response.

### Errors

| Code | Description                  |
| ---- | ---------------------------- |
| 400  | Invalid ID (must be numeric) |
| 404  | Transaction not found        |

***

## Get Transaction by Hash

Get a specific transaction by its **source-chain** transaction hash (EVM tx hash or Casper deploy hash).

```
GET /api/v1/transactions/hash/{txHash}
```

### Parameters

| Name     | In   | Type   | Required | Description                             |
| -------- | ---- | ------ | -------- | --------------------------------------- |
| `txHash` | path | string | yes      | Source transaction hash (EVM or Casper) |

### Response

Same format as individual transaction in list response.

### Errors

| Code | Description           |
| ---- | --------------------- |
| 404  | Transaction not found |

### Examples

**Get by EVM transaction hash:**

```bash
curl "https://api.csprbridge.com/api/v1/transactions/hash/0xabc123def456..."
```

**Get by Casper deploy hash:**

```bash
curl "https://api.csprbridge.com/api/v1/transactions/hash/abc123def456789..."
```

***

## Get Transactions by Address

Get all bridge transactions where an address appears as sender **or** recipient. Unlike the list-endpoint query filters, this accepts EVM addresses **and** Casper addresses/hashes. Paginated.

```
GET /api/v1/transactions/address/{address}
```

### Parameters

| Name      | In    | Type    | Required | Description                          |
| --------- | ----- | ------- | -------- | ------------------------------------ |
| `address` | path  | string  | yes      | EVM address or Casper address/hash   |
| `page`    | query | integer | no       | Page number (default 1)              |
| `limit`   | query | integer | no       | Items per page (default 50, max 100) |

### Response

Same format as the list response (data array + pagination).

***

## Get Pending Transactions

Get all transactions that are not yet `completed` or `failed` — useful for monitoring dashboards.

```
GET /api/v1/transactions/status/pending
```

### Parameters

| Name        | In    | Type   | Required | Description                          |
| ----------- | ----- | ------ | -------- | ------------------------------------ |
| `direction` | query | string | no       | Filter: `eth2casper` or `casper2eth` |

### Response

```json
{
  "success": true,
  "data": [ ... ],
  "count": 3
}
```

***

## Transaction Schema

### Transaction Object

| Field                 | Type     | Description                                   |
| --------------------- | -------- | --------------------------------------------- |
| `id`                  | integer  | Unique database ID                            |
| `txType`              | string   | Transaction type (see below)                  |
| `direction`           | string   | `eth2casper` or `casper2eth`                  |
| `evmChainId`          | integer  | EVM chain ID (e.g., 11155111)                 |
| `evmChainName`        | string   | EVM chain display name                        |
| `sourceChain`         | string   | Source blockchain                             |
| `sourceTxHash`        | string   | Transaction hash on source chain              |
| `sourceBlock`         | integer  | Block number on source chain                  |
| `sourceTimestamp`     | datetime | Timestamp of source transaction               |
| `destinationChain`    | string   | Destination blockchain                        |
| `destinationTxHash`   | string   | Transaction hash on destination (may be null) |
| `amount`              | string   | Token amount (raw, with decimals)             |
| `sender`              | string   | Sender address                                |
| `recipient`           | string   | Recipient address                             |
| `status`              | string   | Current status                                |
| `signaturesCollected` | integer  | Number of relayer signatures collected        |
| `signaturesRequired`  | integer  | Threshold of required signatures              |
| `createdAt`           | datetime | When transaction was first detected           |
| `explorerLinks`       | object   | Block explorer URLs                           |

### Transaction Types

| Type            | Direction  | Description           |
| --------------- | ---------- | --------------------- |
| `lock`          | eth2casper | Lock ERC-20 on EVM    |
| `mint`          | eth2casper | Mint CEP-18 on Casper |
| `burn`          | casper2eth | Burn CEP-18 on Casper |
| `unlock`        | casper2eth | Unlock ERC-20 on EVM  |
| `lock_native`   | casper2eth | Lock native CSPR      |
| `mint_wrapped`  | casper2eth | Mint wCSPR on EVM     |
| `burn_wrapped`  | eth2casper | Burn wCSPR on EVM     |
| `unlock_native` | eth2casper | Unlock native CSPR    |

### Explorer Links Object

```json
{
  "explorerLinks": {
    "source": {
      "url": "https://sepolia.etherscan.io/tx/0x...",
      "explorerName": "Ethereum Sepolia"
    },
    "destination": {
      "url": "https://testnet.cspr.live/deploy/...",
      "explorerName": "CSPR Live (Testnet)"
    }
  }
}
```

***

## Usage Examples

### Track a Bridge Transaction

```javascript
async function trackTransaction(txHash) {
  const response = await fetch(
    `https://api.csprbridge.com/api/v1/transactions/hash/${txHash}`
  );
  const { data: tx } = await response.json();

  console.log(`Status: ${tx.status}`);
  console.log(`Signatures: ${tx.signaturesCollected}/${tx.signaturesRequired}`);

  if (tx.status === 'completed') {
    console.log(`Destination TX: ${tx.destinationTxHash}`);
    console.log(`View: ${tx.explorerLinks.destination.url}`);
  }

  return tx;
}

// Poll until complete
async function waitForCompletion(txHash) {
  while (true) {
    const tx = await trackTransaction(txHash);
    if (tx.status === 'completed' || tx.status === 'failed') {
      return tx;
    }
    await new Promise(r => setTimeout(r, 10000)); // Wait 10s
  }
}
```

### Get User's Transaction History

```javascript
async function getUserTransactions(address) {
  const response = await fetch(
    `https://api.csprbridge.com/api/v1/transactions?address=${address}&limit=100`
  );
  const { data: transactions, pagination } = await response.json();

  const stats = {
    total: pagination.total,
    completed: transactions.filter(t => t.status === 'completed').length,
    pending: transactions.filter(t => t.status !== 'completed' && t.status !== 'failed').length,
  };

  return { transactions, stats };
}
```

### Python Example

```python
import requests

def get_recent_transactions(chain=None, status=None, limit=20):
    """Get recent bridge transactions with optional filters."""
    params = {'limit': limit}
    if chain:
        params['chain'] = chain
    if status:
        params['status'] = status

    response = requests.get(
        'https://api.csprbridge.com/api/v1/transactions',
        params=params
    )
    response.raise_for_status()
    return response.json()['data']

# Get all pending transactions
pending = get_recent_transactions(status='attesting')
print(f"Pending transactions: {len(pending)}")

# Get Base Sepolia transactions
base_txs = get_recent_transactions(chain='base-sepolia', limit=50)
for tx in base_txs:
    print(f"{tx['txType']}: {tx['amount']} ({tx['status']})")
```

### curl with jq

```bash
# Get latest 5 completed transactions
curl -s "https://api.csprbridge.com/api/v1/transactions?status=completed&limit=5" | \
  jq '.data[] | {hash: .sourceTxHash, amount: .amount, status: .status}'

# Count transactions by status
curl -s "https://api.csprbridge.com/api/v1/transactions?limit=100" | \
  jq '.data | group_by(.status) | map({status: .[0].status, count: length})'

# Get transactions for specific address
curl -s "https://api.csprbridge.com/api/v1/transactions?address=0x1234...5678" | \
  jq '.data | length'
```

***

## Webhooks (Coming Soon)

Real-time transaction status updates via webhooks are planned for a future release.

Proposed webhook payload:

```json
{
  "event": "transaction.status_changed",
  "timestamp": "2024-01-15T12:35:00Z",
  "data": {
    "txHash": "0xabc123...",
    "previousStatus": "attesting",
    "newStatus": "completed",
    "transaction": { ... }
  }
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.astralbeam.io/api-reference/transactions.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.