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

# GET /v1/transactions — Your Balance Ledger

> Every movement on your CSBoard balance — purchases, refunds, sales, deposits — newest first, keyset paginated. The endpoint to reconcile against.

The transactions endpoint is your money ledger: one row per movement on your balance, newest first. It is the endpoint to reconcile against — a failed purchase and the refund that made you whole are two rows carrying the same `order_id`.

**Authentication required.** Send your key as `Authorization: Bearer csb_pub_...`. Any valid key works; the trading flag is not needed.

<Note>
  A `cancelled` or `failed` order is **always refunded**, and the credit usually lands within seconds. You do not need to poll this endpoint to find out whether a refund happened — the order itself carries a [`refund`](/api-reference/get-orders) object. Use `/v1/transactions` when you want the full money trail: bookkeeping, an internal statement, or an end-of-day reconciliation.
</Note>

## Query parameters

<ParamField query="limit" type="integer" default="50">
  Results per page. Minimum `1`, maximum `100`.
</ParamField>

<ParamField query="type" type="string">
  Filter by movement type. One of: `purchase`, `refund`, `sale`, `deposit`, `withdrawal`, `bonus`, `fee`.
</ParamField>

<ParamField query="start_unix_time" type="integer">
  Only return entries created at or after this Unix timestamp (seconds).
</ParamField>

<ParamField query="end_unix_time" type="integer">
  Only return entries created at or before this Unix timestamp (seconds).
</ParamField>

<ParamField query="cursor" type="string">
  Keyset cursor from a previous response's `meta.next_cursor`. Pass it to fetch the next page.
</ParamField>

## Response fields

<ResponseField name="data" type="Transaction[]" required>
  Array of ledger entries for this page.

  <Expandable title="Transaction object">
    <ResponseField name="id" type="string" required>
      Ledger entry id.
    </ResponseField>

    <ResponseField name="type" type="string" required>
      What moved the money. One of: `purchase`, `refund`, `sale`, `deposit`, `withdrawal`, `bonus`, `fee`, `adjustment`.
    </ResponseField>

    <ResponseField name="amount_usd" type="number" required>
      Signed. Negative means money left your balance, positive means it came in.
    </ResponseField>

    <ResponseField name="balance_after_usd" type="number" required>
      Your balance immediately after this entry.
    </ResponseField>

    <ResponseField name="order_id" type="string | null">
      The order this movement belongs to. `null` for movements that are not tied to an order (a deposit, a bonus).
    </ResponseField>

    <ResponseField name="order_kind" type="string | null">
      Whether `order_id` refers to a `buy` or a `sell` order.
    </ResponseField>

    <ResponseField name="created_at" type="datetime" required>
      ISO 8601 timestamp.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object" required>
  <Expandable title="meta object">
    <ResponseField name="next_cursor" type="string | null" required>
      Pass back as `cursor` to fetch the next page. `null` on the last page.
    </ResponseField>

    <ResponseField name="per_page" type="integer" required>
      Page size used for this response.
    </ResponseField>
  </Expandable>
</ResponseField>

## Example request

```bash theme={null}
curl "https://csboard.com/v1/transactions?type=refund&limit=50" \
  -H "Authorization: Bearer csb_pub_..."
```

## Example response

A purchase that could not be delivered, and its refund — same `order_id`, seconds apart:

```json theme={null}
{
  "data": [
    {
      "id": "tx_01J9Z3M2A7",
      "type": "refund",
      "amount_usd": 1.28,
      "balance_after_usd": 429.46,
      "order_id": "cmrkm405x0709yj01b8lmzk62",
      "order_kind": "buy",
      "created_at": "2026-07-14T12:13:15Z"
    },
    {
      "id": "tx_01J9Z3M1Q4",
      "type": "purchase",
      "amount_usd": -1.28,
      "balance_after_usd": 428.18,
      "order_id": "cmrkm405x0709yj01b8lmzk62",
      "order_kind": "buy",
      "created_at": "2026-07-14T12:13:15Z"
    }
  ],
  "meta": { "next_cursor": "eyJ0IjoiMjAyNi0wNy0xNFQxMjoxMzoxNVoifQ==", "per_page": 50 }
}
```

## Reconciling a day

Walk the ledger with the cursor and sum by type — purchases and refunds net out against the orders you know:

```python theme={null}
import requests

HEADERS = {"Authorization": "Bearer csb_pub_..."}
cursor, totals = None, {}

while True:
    r = requests.get(
        "https://csboard.com/v1/transactions",
        params={"limit": 100, "start_unix_time": 1752451200, "cursor": cursor},
        headers=HEADERS,
    ).json()

    for tx in r["data"]:
        totals[tx["type"]] = round(totals.get(tx["type"], 0) + tx["amount_usd"], 2)

    cursor = r["meta"]["next_cursor"]
    if not cursor:
        break

print(totals)  # {'purchase': -524.89, 'refund': 65.09, ...}
```

## Error codes

| HTTP status | Code                                  | Meaning                                                                      |
| ----------- | ------------------------------------- | ---------------------------------------------------------------------------- |
| 401         | `missing_api_key` / `invalid_api_key` | Missing or invalid API key.                                                  |
| 422         | `invalid_request`                     | Invalid query parameters (unknown `type`, bad cursor, `limit` out of range). |
| 429         | `rate_limit_exceeded`                 | Too many requests. Back off for the `Retry-After` header value.              |


## OpenAPI

````yaml GET /transactions
openapi: 3.1.0
info:
  title: CSBoard API
  version: 1.0.0
  description: >-
    Market data over the CSBoard marketplace — live listings, floats, stickers,
    minAsk prices, FX rates — plus opt-in buying straight from your balance.
    Free to read, key-gated, built for automation.
  contact:
    name: CSBoard
    url: https://csboard.com/docs
servers:
  - url: https://csboard.com/v1
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Status
    description: Liveness and freshness probes.
  - name: Market data
    description: Read the live catalog, prices, and FX rates.
  - name: Trading
    description: Buy listings from your CSBoard balance. Opt-in, key-gated.
  - name: Account
    description: Your balance, settled funds, and trading status.
  - name: Webhooks
    description: Register an endpoint and receive signed order updates instead of polling.
paths:
  /transactions:
    get:
      tags:
        - Account
      summary: Your balance ledger
      description: >-
        Every movement on your API balance — purchases, refunds, sales, deposits
        — newest first, keyset paginated. Use it to reconcile: a failed purchase
        and its refund are two rows sharing the same `order_id`.
      operationId: getTransactions
      parameters:
        - name: limit
          in: query
          description: Results per page. 1–100. Default 50.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - name: type
          in: query
          description: Filter by movement type.
          schema:
            type: string
            enum:
              - purchase
              - refund
              - sale
              - deposit
              - withdrawal
              - bonus
              - fee
        - name: start_unix_time
          in: query
          description: Only entries created at or after this Unix timestamp (seconds).
          schema:
            type: integer
        - name: end_unix_time
          in: query
          description: Only entries created at or before this Unix timestamp (seconds).
          schema:
            type: integer
        - name: cursor
          in: query
          description: Keyset cursor from a previous response's `meta.next_cursor`.
          schema:
            type: string
      responses:
        '200':
          description: A page of ledger entries.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Transaction'
                  meta:
                    type: object
                    properties:
                      next_cursor:
                        type:
                          - string
                          - 'null'
                      per_page:
                        type: integer
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
components:
  schemas:
    Transaction:
      type: object
      properties:
        id:
          type: string
          description: Ledger entry id.
        type:
          type: string
          enum:
            - purchase
            - refund
            - sale
            - deposit
            - withdrawal
            - bonus
            - fee
            - adjustment
          description: What moved the money.
        amount_usd:
          type: number
          description: 'Signed: negative left your balance, positive came in.'
          example: -1.28
        balance_after_usd:
          type: number
          description: Your balance right after this entry.
          example: 428.18
        order_id:
          type:
            - string
            - 'null'
          description: >-
            The order this movement belongs to, or `null` for non-order
            movements (deposits, bonuses).
        order_kind:
          type:
            - string
            - 'null'
          enum:
            - buy
            - sell
            - null
          description: Whether `order_id` refers to a buy or a sell order.
        created_at:
          type: string
          format: date-time
      required:
        - id
        - type
        - amount_usd
        - balance_after_usd
        - created_at
    Error:
      type: object
      description: >-
        All errors return { code, detail }. Some carry extra fields (e.g.
        price_moved adds current_total_usd, insufficient_balance adds
        required_usd/current_usd).
      properties:
        code:
          type: string
          description: >-
            Machine-readable error code, e.g. rate_limit_exceeded,
            trading_not_enabled, price_moved.
        detail:
          type: string
          description: Human-readable explanation.
      required:
        - code
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Send your key as a Bearer token on every request: `Authorization: Bearer
        csb_pub_...`. Generate keys in your CSBoard profile.

````