# Transactions

The following endpoints are use to create and retrieve transactions from the system.

* [Get the list of all transactions](#get-the-list-of-all-transactions)
* [Get one specific transaction](#get-one-specific-transaction)
* [Create a new transaction](#create-a-new-transaction)

## The `transaction` object

The `transaction` object represents an operation (deposit or withdrawal) executed by it's identity owner.

#### Transaction entity model

<table><thead><tr><th width="230">Name</th><th width="150" align="center">Type</th><th>Description</th><th>Constraints</th></tr></thead><tbody><tr><td>amount</td><td align="center"><code>String</code></td><td>Transaction amount.</td><td><code>Not Null</code></td></tr><tr><td>appId</td><td align="center"><code>String</code></td><td>Application ID. Format: <code>uuid</code>.</td><td></td></tr><tr><td>code</td><td align="center"><code>String</code></td><td>Transaction code.</td><td>Enum:[<code>deposit:stablecoin:usdc</code>, <code>deposit:wire:usd</code>]</td></tr><tr><td>createdAt</td><td align="center"><code>DateTime</code></td><td>Transaction created at date.</td><td><code>Not Null</code></td></tr><tr><td>currency</td><td align="center"><code>String</code></td><td>Transaction currency.</td><td>Enum:[<code>USD</code>]</td></tr><tr><td>deletedAt</td><td align="center"><code>DateTime</code></td><td>Transaction deleted at date.</td><td></td></tr><tr><td>destinationAddress</td><td align="center"><code>String</code></td><td>Transaction destination address.</td><td></td></tr><tr><td>addressId</td><td align="center"><code>String</code></td><td>Transaction address id.</td><td></td></tr><tr><td>externalReference</td><td align="center"><code>String</code></td><td>Transaction external reference.</td><td></td></tr><tr><td>id</td><td align="center"><code>String</code></td><td>Transaction identifier. Format: <code>uuid</code>.</td><td><code>Not Null</code></td></tr><tr><td>identityId</td><td align="center"><code>String</code></td><td>Transaction identity owner. Format: <code>uuid</code></td><td></td></tr><tr><td>metadata</td><td align="center"><code>Object</code></td><td>Transaction metadata.</td><td></td></tr><tr><td>originAddress</td><td align="center"><code>String</code></td><td>Transaction origin address.</td><td></td></tr><tr><td>status</td><td align="center"><code>String</code></td><td>Transaction status.</td><td>Enum:[<code>pending</code>, <code>approved</code>, <code>confirmed</code>, <code>failed</code>, <code>canceled</code>, <code>review</code>]</td></tr><tr><td>transactionHash</td><td align="center"><code>String</code></td><td>Transaction hash.</td><td></td></tr><tr><td>type</td><td align="center"><code>String</code></td><td>Transaction type.</td><td>Enum:[<code>deposit</code>, <code>transfer</code>, <code>withdrawal</code>]</td></tr><tr><td>updatedAt</td><td align="center"><code>DateTime</code></td><td>Transaction updated at date.</td><td><code>Not Null</code></td></tr></tbody></table>

## Get the list of all transactions

`GET /transactions`

Get transactions list.

**Available filters**

| Name                |       Type       | Example                              |
| ------------------- | :--------------: | ------------------------------------ |
| addressId           |     `default`    | `filter[addressId]=foobar`           |
| code                | `default,in,nin` | `filter[code]=in:foobar`             |
| currency            | `default,in,nin` | `filter[currency]=nin:foobar`        |
| destinationAddress  | `default,in,nin` | `filter[destinationAddress]=foobar`  |
| earnDistributionId  |     `default`    | `filter[earnDistributionId]=foobar`  |
| id                  | `default,in,nin` | `filter[id]=foobar`                  |
| identityId          | `default,in,nin` | `filter[identityId]=foobar`          |
| originAddress       | `default,in,nin` | `filter[originAddress]=foobar`       |
| originTransactionId |     `default`    | `filter[originTransactionId]=foobar` |
| status              | `default,in,nin` | `filter[status]=in:foobar`           |
| transactionHash     | `default,in,nin` | `filter[transactionHash]=in:foobar`  |
| type                | `default,in,nin` | `filter[type]=in:foobar`             |

**Available sorts**

| Name      | Example                                                            |
| --------- | ------------------------------------------------------------------ |
| createdAt | <p><code>sort=createdAt</code><br><code>sort=-createdAt</code></p> |
| updatedAt | <p><code>sort=updatedAt</code><br><code>sort=-updatedAt</code></p> |

**Available includes**

| Name    | Example           |
| ------- | ----------------- |
| address | `include=address` |

**Paginate options**

| Name   | Description                                             | Example          |
| ------ | ------------------------------------------------------- | ---------------- |
| size   | Defines the number of results per page. Default = 30.   | `page[size]=2`   |
| number | Defines the number of the page to retrieve. Default = 1 | `page[number]=2` |
| all    | Return all identities without pagination                | `all=true`       |

**Response Options**

**200 OK**

Request example:

```
GET <hostname>/transactions
```

Response example:

```
{
  "data": [{
    "addressId": null,
    "amount": "10.00000000",
    "appId": "e7941059-74c6-4b3f-b029-d3aa03d1ea44",
    "code": "deposit:internal:usd",
    "createdAt": "2020-10-28T17:40:55.501Z",
    "currency": "USD",
    "deletedAt": null,
    "destinationAddress": "0x71c7656ec7ab88b098defb751b7401b5f6d8976f",
    "earnDistributionId": null,
    "externalReference": null,
    "id": "e7941059-74c6-4b3f-b029-d3aa03d1ea44",
    "identityId": "e7941059-74c6-4b3f-b029-d3aa03d1ea44",
    "metadata": {},
    "originAddress": null,
    "status": "pending",
    "transactionHash": "0xb5c8bd9430b6cc87a0e2fe110ece6bf527fa4f170a4bc8cd032f768fc5219838",
    "type": "deposit",
    "updatedAt": "2020-10-28T17:40:55.501Z"
  }],
  "total": 1
}
```

## Get one specific transaction

`GET /transactions/:id`

Get transaction by id.

**Available includes**

| Name    | Example           |
| ------- | ----------------- |
| address | `include=address` |

**Response Options**

**400 Bad Request**

* validation\_failed
  * If id is invalid.

**404 Not Found**

* transaction\_not\_found

**200 OK**

Request example:

```
GET <hostname>/transactions/e7941059-74c6-4b3f-b029-d3aa03d1ea44
```

Response example:

```
{
  "data": {
    "addressId": null,
    "amount": "10.00000000",
    "appId": "e7941059-74c6-4b3f-b029-d3aa03d1ea44",
    "code": "deposit:internal:usd",
    "createdAt": "2020-10-28T17:40:55.501Z",
    "currency": "USD",
    "deletedAt": null,
    "destinationAddress": "0x71c7656ec7ab88b098defb751b7401b5f6d8976f",
    "earnDistributionId": null,
    "externalReference": null,
    "id": "e7941059-74c6-4b3f-b029-d3aa03d1ea44",
    "identityId": "e7941059-74c6-4b3f-b029-d3aa03d1ea44",
    "metadata": {},
    "originAddress": null,
    "status": "pending",
    "transactionHash": "0xb5c8bd9430b6cc87a0e2fe110ece6bf527fa4f170a4bc8cd032f768fc5219838",
    "type": "deposit",
    "updatedAt": "2020-10-28T17:40:55.501Z"
  }
}
```

## Create a new transaction

`POST /transactions`

Creates a transaction.

**Request Parameters**

**Body parameters**

| Name               |   Type   | Description                                | Constraints                                                                | Required |
| ------------------ | :------: | ------------------------------------------ | -------------------------------------------------------------------------- | :------: |
| amount             | `String` | Transaction amount.                        | `Not null`                                                                 |  `true`  |
| chain              | `String` | Transaction chain.                         | \[`ALGO`,`AVAX`,`ETH`,`SOL`,`TRX`,`XLM`]. Only for stablecoin transactions |          |
| code               | `String` | Transaction code.                          | \[`deposit:stablecoin:usdc`,`deposit:wire:usd`]                            |  `true`  |
| currency           | `String` | Transaction currency                       | \[`USD`]                                                                   |  `true`  |
| destinationAddress | `String` | Transaction destination address.           |                                                                            |  `true`  |
| identityId         | `String` | Transaction identity owner. Format: `uuid` |                                                                            |  `true`  |
| originAddress      | `String` | Transaction origin address.                |                                                                            |          |
| paymentMethod      | `String` | Transaction payment method.                | \[`wire`,`internationalWire`]. Only for Wire transactions                  |          |

**Response Options**

**400 Bad Request**

* validation\_failed
  * If the required parameters are not provided.
  * If additional parameters are provided.
  * If some of the parameters type is invalid.
  * If some of the parameters constraints is not respected.

**422 Unprocessable Entity**

* chain\_is\_not\_available
  * If the request chain is not active.

**200 OK**

Request example:

```
POST <hostname>/transactions

{
  "amount": "10",
  "chain": "XLM",
  "code": "deposit:stablecoin:usdc",
  "currency": "USD",
  "destinationAddress": "0x71c7656ec7ab88b098defb751b7401b5f6d8976f",
  "identityId": "e7941059-74c6-4b3f-b029-d3aa03d1ea44"
}
```

Response example:

```
{
  "data": {
    "addressId": "e7941059-74c6-4b3f-b029-d3aa03d1ea42",
    "amount": "10.00000000",
    "appId": "e7941059-74c6-4b3f-b029-d3aa03d1ea44",
    "code": "deposit:stablecoin:usdc",
    "createdAt": "2020-10-28T17:40:55.501Z",
    "currency": "USD",
    "deletedAt": null,
    "destinationAddress": "0x71c7656ec7ab88b098defb751b7401b5f6d8976f",
    "externalReference": null,
    "id": "e7941059-74c6-4b3f-b029-d3aa03d1ea44",
    "identityId": "e7941059-74c6-4b3f-b029-d3aa03d1ea44",
    "metadata": {
      "addressId": "e7941059-74c6-4b3f-b029-d3aa03d1ea42",
      "transactionDetails": {
        "address": "0x99c7656ec7ab88b098defb751b7401b5f6d8976f",
        "addressTag": "xyyz"
      }
    },
    "originAddress": null,
    "status": "pending",
    "transactionDetails": {
      "address": "0x99c7656ec7ab88b098defb751b7401b5f6d8976f",
      "addressTag": "xyyz"
    },
    "transactionHash": null,
    "type": "deposit",
    "updatedAt": "2020-10-28T17:40:55.501Z"
  }
}
```

Request example:

```
POST <hostname>/transactions

{
  "amount": "10",
  "code": "deposit:wire:usd",
  "currency": "USD",
  "destinationAddress": "0x71c7656ec7ab88b098defb751b7401b5f6d8976f",
  "identityId": "e7941059-74c6-4b3f-b029-d3aa03d1ea44",
  "paymentMethod": "wire"
}
```

Response example:

```
{
  "data": {
    "addressId": "e7941059-74c6-4b3f-b029-d3aa03d1ea42",
    "amount": "10.00000000",
    "appId": "e7941059-74c6-4b3f-b029-d3aa03d1ea44",
    "code": "deposit:wire:usd",
    "createdAt": "2020-10-28T17:40:55.501Z",
    "currency": "USD",
    "deletedAt": null,
    "destinationAddress": "0x71c7656ec7ab88b098defb751b7401b5f6d8976f",
    "externalReference": "e7941059-74c6-4b3f-b029-d3aa03d1ea43",
    "id": "e7941059-74c6-4b3f-b029-d3aa03d1ea44",
    "identityId": "e7941059-74c6-4b3f-b029-d3aa03d1ea44",
    "metadata": {
      "paymentMethod": "wire",
      "transactionDetails": {
        "bankName": "ROYAL BUSINESS BANK",
        "reference": "CUSCTW6GA",
        "swiftCode": "RBBCUS6L",
        "bankAccountName": "Prime Trust, LLC",
        "bankAccountNumber": "2030136050"
      }
    },
    "originAddress": null,
    "status": "pending",
    "transactionDetails": {
      "bankName": "ROYAL BUSINESS BANK",
      "reference": "CUSCTW6GA",
      "swiftCode": "RBBCUS6L",
      "bankAccountName": "Prime Trust, LLC",
      "bankAccountNumber": "2030136050"
    },
    "transactionHash": null,
    "type": "deposit",
    "updatedAt": "2020-10-28T17:40:55.501Z"
  }
}
```


---

# Agent Instructions: 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:

```
GET https://developers.publicmint.io/api/reference/transactions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.