> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gettrxn.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Crypto transactions

> View and manually create cryptocurrency transactions for your account. Transactions include allocation information showing how payments are applied to invoices.

This API allows you to view and manually create cryptocurrency transactions for your account.

## The crypto transaction object

<ResponseField name="id" type="string">
  Unique identifier with `trxn_` prefix (e.g., `trxn_abc123def456`).
</ResponseField>

<ResponseField name="object" type="string">
  Always `"crypto_transaction"`.
</ResponseField>

<ResponseField name="amount" type="string">
  Transaction amount (string to preserve precision).
</ResponseField>

<ResponseField name="transaction_id" type="string">
  Blockchain transaction hash.
</ResponseField>

<ResponseField name="transaction_source" type="string">
  Source of the transaction: `manual_entry` or `blockchain`.
</ResponseField>

<ResponseField name="timestamp" type="string">
  When the transaction occurred (ISO 8601).
</ResponseField>

<ResponseField name="currency" type="string">
  Currency code (e.g., `BTC`, `ETH`).
</ResponseField>

<ResponseField name="from_address_id" type="string">
  Sending address ID. May be `null`.
</ResponseField>

<ResponseField name="from_address" type="string">
  Sending address. May be `null`.
</ResponseField>

<ResponseField name="to_address_id" type="string">
  Receiving address ID.
</ResponseField>

<ResponseField name="to_address" type="string">
  Receiving address.
</ResponseField>

<ResponseField name="allocations" type="array">
  Transaction allocations to invoices.

  <Expandable title="allocation properties">
    <ResponseField name="allocations[].id" type="string">
      Unique identifier for the allocation.
    </ResponseField>

    <ResponseField name="allocations[].invoice_id" type="string">
      Invoice ID this allocation applies to.
    </ResponseField>

    <ResponseField name="allocations[].amount_applied" type="string">
      Amount applied to the invoice.
    </ResponseField>

    <ResponseField name="allocations[].created_at" type="string">
      When the allocation was created (ISO 8601).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created_at" type="string">
  When the record was created (ISO 8601).
</ResponseField>

<ResponseField name="updated_at" type="string">
  When the record was last updated (ISO 8601).
</ResponseField>

## List crypto transactions

```
GET /v1/crypto_transactions
```

Retrieves a paginated list of all crypto transactions in your account. Transactions are ordered by timestamp (newest first).

<ParamField query="page" type="integer" default="1">
  Page number for pagination. Results are returned 25 items per page.
</ParamField>

```bash theme={null}
curl https://api.gettrxn.com/v1/crypto_transactions \
  -H "Authorization: Bearer $TRXN_TOKEN"
```

```json Response theme={null}
{
  "crypto_transactions": [
    {
      "id": "trxn_abc123def456",
      "object": "crypto_transaction",
      "amount": "0.5",
      "transaction_id": "0x1234567890abcdef...",
      "transaction_source": "manual_entry",
      "timestamp": "2025-01-25T12:00:00Z",
      "currency": "BTC",
      "from_address_id": "addr_xyz789",
      "from_address": "bc1q...",
      "to_address_id": "addr_abc123",
      "to_address": "bc1q...",
      "allocations": [
        {
          "id": "alloc_123",
          "invoice_id": "inv_456",
          "amount_applied": "0.25",
          "created_at": "2025-01-25T12:30:00Z"
        }
      ],
      "created_at": "2025-01-25T12:00:00Z",
      "updated_at": "2025-01-25T12:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pages": 3,
    "count": 67
  }
}
```

## Get crypto transaction

```
GET /v1/crypto_transactions/:id
```

Retrieves a specific crypto transaction by ID, including its allocations.

<ParamField path="id" type="string" required>
  The transaction's ID (e.g., `trxn_abc123def456`).
</ParamField>

```bash theme={null}
curl https://api.gettrxn.com/v1/crypto_transactions/trxn_abc123def456 \
  -H "Authorization: Bearer $TRXN_TOKEN"
```

```json Response theme={null}
{
  "id": "trxn_abc123def456",
  "object": "crypto_transaction",
  "amount": "0.5",
  "transaction_id": "0x1234567890abcdef...",
  "transaction_source": "manual_entry",
  "timestamp": "2025-01-25T12:00:00Z",
  "currency": "BTC",
  "from_address_id": "addr_xyz789",
  "from_address": "bc1q...",
  "to_address_id": "addr_abc123",
  "to_address": "bc1q...",
  "allocations": [
    {
      "id": "alloc_123",
      "invoice_id": "inv_456",
      "amount_applied": "0.25",
      "created_at": "2025-01-25T12:30:00Z"
    }
  ],
  "created_at": "2025-01-25T12:00:00Z",
  "updated_at": "2025-01-25T12:00:00Z"
}
```

## Create crypto transaction

```
POST /v1/crypto_transactions
```

Creates a new crypto transaction manually. This is useful for recording transactions that were not automatically detected by the system.

<ParamField body="to_address_id" type="string" required>
  The receiving address ID (e.g., `addr_abc123`). Must belong to your account.
</ParamField>

<ParamField body="amount" type="string" required>
  The transaction amount (as a string to preserve precision).
</ParamField>

<ParamField body="currency_code" type="string" required>
  The currency code (e.g., `BTC`, `ETH`).
</ParamField>

<ParamField body="transaction_id" type="string" required>
  The blockchain transaction hash/ID.
</ParamField>

<ParamField body="timestamp" type="string">
  The transaction timestamp (ISO 8601 format). Defaults to current time.
</ParamField>

<ParamField body="from_address_id" type="string">
  The sending address ID (e.g., `addr_xyz789`).
</ParamField>

```bash theme={null}
curl -X POST https://api.gettrxn.com/v1/crypto_transactions \
  -H "Authorization: Bearer $TRXN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to_address_id": "addr_abc123",
    "amount": "0.5",
    "currency_code": "BTC",
    "transaction_id": "0x1234567890abcdef...",
    "timestamp": "2025-01-25T12:00:00Z"
  }'
```

```json Response theme={null}
{
  "id": "trxn_new123abc456",
  "object": "crypto_transaction",
  "amount": "0.5",
  "transaction_id": "0x1234567890abcdef...",
  "transaction_source": "manual_entry",
  "timestamp": "2025-01-25T12:00:00Z",
  "currency": "BTC",
  "from_address_id": null,
  "from_address": null,
  "to_address_id": "addr_abc123",
  "to_address": "bc1q...",
  "allocations": [],
  "created_at": "2025-01-25T14:30:00Z",
  "updated_at": "2025-01-25T14:30:00Z"
}
```

### Error responses

```json Address not found theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "Crypto address not found",
    "param": "to_address_id"
  }
}
```

```json Unsupported currency theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "Currency not found: DOGE",
    "param": "currency_code"
  }
}
```

## The allocation object

| Field            | Type   | Description                                 |
| ---------------- | ------ | ------------------------------------------- |
| `id`             | string | Unique identifier for the allocation.       |
| `invoice_id`     | string | Invoice ID this allocation applies to.      |
| `amount_applied` | string | Amount applied to the invoice.              |
| `created_at`     | string | When the allocation was created (ISO 8601). |

## Sandbox support

<Note>
  The API respects sandbox scoping. If your API token is associated with a sandbox, you can only access transactions created in that sandbox. Manually created transactions will be isolated from production data.
</Note>