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

# GET /api/transactions — List AI Transaction History

> GET /api/transactions — returns paginated history of all AI-initiated transactions across all sessions, with status and Stellar hashes.

Retrieve a list of every transaction submitted by your AI sessions, ordered newest first. Each record includes the asset, amount, recipient Stellar address, current lifecycle status, and — once confirmed — the Stellar transaction hash you can look up on any Stellar explorer. Use this endpoint to audit spending, reconcile balances, and track which transactions are still in flight.

## Endpoint

```
GET /api/transactions
```

## Authentication

All requests must include a valid bearer token in the `Authorization` header, or a `pay3_session` cookie obtained during wallet authentication.

```
Authorization: Bearer <token>
```

## Query parameters

**limit** `number` (default: 50)

Maximum number of transactions to return. Defaults to `50`. Pass a lower value to reduce response size.

## Response

Returns an array of transaction objects ordered by `createdAt` descending (newest first).

### Response fields

**id** `string` *required*

Unique UUID for this transaction.

**action** `string` *required*

The operation type. One of:

* `TRANSFER` — an asset transfer to a recipient address
* `CHECK_BALANCE` — a balance read (does not move funds)
* `VIEW_TRANSACTION_HISTORY` — a history read (does not move funds)

**asset** `string` *required*

Ticker of the asset involved, e.g. `"USDC"` or `"XLM"`.

**amount** `string`

Amount involved, expressed as a decimal string (e.g. `"42.5000000"`). May be `null` for non-transfer actions.

**recipientAddress** `string`

The resolved destination Stellar address (G-address). Populated for `TRANSFER` actions once the recipient has been resolved. `null` for non-transfer actions.

**recipientInput** `string`

The raw recipient value supplied by the AI, which may be a Stellar address, a contact alias, or a display name. Use this to understand what the AI asked to send to.

**status** `string` *required*

Current lifecycle status of the transaction. One of:

* `CREATED` — transaction record created, not yet validated
* `VALIDATING` — policy engine is evaluating the request
* `AUTO_APPROVED` — passed all policy checks; being submitted automatically
* `PENDING_APPROVAL` — exceeds `manualApprovalThreshold`; awaiting your review
* `APPROVED` — you approved it; being submitted to the network
* `SIGNING` — transaction envelope is being signed
* `SUBMITTING` — signed envelope is being broadcast to the Stellar network
* `SUCCESS` — confirmed on the Stellar network
* `FAILED` — submission failed; see `rejectionReason` via [GET /api/transactions/:id](https://pay3.mintlify.site/api-reference/transactions/get.md)
* `REJECTED` — rejected by the policy engine before submission
* `EXPIRED` — the approval window elapsed before you approved
* `CANCELLED` — cancelled before reaching the network

**policyDecision** `string` *required*

The decision made by the policy engine:

* `AUTO_EXECUTE` — transaction was within all limits and submitted without approval
* `PENDING_APPROVAL` — transaction exceeded `manualApprovalThreshold` and was routed to the approval queue
* `REJECTED` — transaction violated a policy rule and was blocked outright

**stellarTransactionHash** `string`

The Stellar transaction hash, populated once the transaction reaches `SUCCESS`. Use this to look up the transaction on [Stellar Expert](https://stellar.expert) or [Horizon](https://horizon.stellar.org).

**aiSessionId** `string` *required*

UUID of the AI session that initiated this transaction.

**aiSession** `object` *required*

Summary of the AI session that submitted this transaction.

**aiSession fields**

**id** `string` *required*

UUID of the AI session.

**clientType** `string` *required*

AI client type (e.g. `"CURSOR"`, `"CLAUDE"`).

**contact** `object`

If the recipient address matched a saved contact, this object contains the contact's details. `null` when no match was found.

**contact fields**

**id** `string` *required*

UUID of the matched contact.

**displayName** `string` *required*

Human-readable name of the contact.

**createdAt** `string` *required*

ISO 8601 timestamp when the transaction was created.

## Example request

```bash theme={null}
curl "https://api.pay3.dev/api/transactions?limit=20" \
  -H "Authorization: Bearer <token>"
```

## Example response

```json theme={null}
[
  {
    "id": "d4e5f6a7-abcd-1234-ef56-789012345678",
    "action": "TRANSFER",
    "asset": "USDC",
    "amount": "42.5000000",
    "recipientAddress": "GBXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "recipientInput": "alice",
    "status": "SUCCESS",
    "policyDecision": "AUTO_EXECUTE",
    "stellarTransactionHash": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
    "aiSessionId": "e3b0c442-98fc-1c14-9afb-f4c8996fb924",
    "aiSession": {
      "id": "e3b0c442-98fc-1c14-9afb-f4c8996fb924",
      "clientType": "CURSOR"
    },
    "contact": {
      "id": "c1a2b3d4-0001-4abc-8def-000000000001",
      "displayName": "Alice Johnson"
    },
    "createdAt": "2025-07-08T12:00:00.000Z"
  },
  {
    "id": "c3b2a1f0-9876-5432-fedc-ba0987654321",
    "action": "TRANSFER",
    "asset": "XLM",
    "amount": "100.0000000",
    "recipientAddress": "GCYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY",
    "recipientInput": "GCYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY",
    "status": "PENDING_APPROVAL",
    "policyDecision": "PENDING_APPROVAL",
    "stellarTransactionHash": null,
    "aiSessionId": "e3b0c442-98fc-1c14-9afb-f4c8996fb924",
    "aiSession": {
      "id": "e3b0c442-98fc-1c14-9afb-f4c8996fb924",
      "clientType": "CURSOR"
    },
    "contact": null,
    "createdAt": "2025-07-08T11:45:00.000Z"
  }
]
```

> [!NOTE]
>
> Transactions with a status of `PENDING_APPROVAL` are awaiting your manual approval in the [approvals queue](https://pay3.mintlify.site/api-reference/approvals/list.md). They will transition to `EXPIRED` if not approved within 2 minutes of the approval request being created.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.