# Inventory
## Overview
Get information about the carbon credits you own that haven't been retired yet. You can also see the purchase history of each project/vintage.
## Example cURL Request
```sh
curl --request GET 'https://${BASE_URL}/api/inventory?page=1&per_page=20' \
--header 'Authorization: Bearer ${API_KEY}'
```
## Wallets
Your inventory is held in "wallets". Each wallet has a type and is associated to a specific project and vintage. The only wallet type currently supported is `CAAS`, but more wallet types may be added in the future.
### Fractionalised Retirements
The wallet data contains the quantity of carbon credits you own, in grams, that haven't yet been retired. This can occur when using the [Request Retirement](/api-endpoints/caas/requestretirement.md) and passing a value for `quantity_grams` that isn't in whole tonnes i.e. the value doesn't divide evenly by 1,000,000. This is known as a "fractionalised" retirement because you are requesting the retirement of a fraction of a tonne.
Purchases are always made in whole tonnes. As an example, if you retire 750,000 (three quarters of a tonne) the system will purchase a whole tonne (1,000,000 grams) but only queue 750,000 grams for retirement. This is due to a limitation on the underlying registries where retirements can only occur in whole tonnes. In this example, you still own the remaining 250,000 grams but they will not be queued for retirement.
You can use this end point to view those 250,000 grams.
## When To Use This Endpoint
If you always retire in whole tonnes you do not need to use this endpoint as purchases are made on the fly at the same time as retirement so your inventory will always be zero.
If you retire in fractions you may wish to check your inventory before purchasing more credits from the market so you use up your inventory first.
## Trade History
The trade history supplied with each wallet is useful to see what prices you have paid for these credits in the past. For example, in a scenario where you sell credits to your own customers, you may take the last price paid for a specific project/vintage in order to determine what price to charge your own customers.
This is in contrast to when you might use the market data which will have the current price. If we did not supply the trade history you wouldn't know what you paid for the credits and therefore you couldn't be sure what to charge your own customers.
## Endpoint Specification
## Get inventory for tenant
`GET` `/api/inventory`
Get information about the carbon credits you own that haven't been retired yet. You can also see the purchase history for each project/vintage.
#### Query Parameters
| Name | Type | Description |
| --------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| page | number | For pagination. Which page would you like to be returned? The default value is 1. |
| per\_page | number | For pagination. How many `project` results you would like per page. The default value is 20. |
| trades\_per\_wallet | number | The number of trades shown per wallet. By default all trades are returned. The array is ordered by most recent trades at the top. |
| trade\_type | string | Which types of trade to return. By default all types of trades are shown. Valid values are `BUY` and `SELL`. |
| wallet\_min\_quantity | number | Defines the minimum available balance (in grams) a wallet must contain to be returned. By default, this value is 0 so it shows all wallets. Passing a value of 1 will return all non-zero wallets. |
#### Headers
| Name | Type | Description |
| ----------------------------------------------- | ------ | ------------------- |
| Authorization\* | string | `Bearer ${API_KEY}` |
{% tabs %}
{% tab title="200: OK " %}
`price_cents` is per tonne. 1 tonne is 1,000,000 grams. Purchases are always made in whole tonnes.
Prices are in USD cents.
`quantity_grams` is the amount of credits, in grams, that you own that has not been retired.
If a trade type is `BUY` the `quantity_grams` and `price_cents` is how much you purchased and at what price.
If a trade type is `SELL` the `quantity_grams` and `price_cents` is how much you sold and at what price. Selling isn't currently possible for CaaS customers so you would only see `BUY` trade types. This may be a feature we implement in the future.
{% tabs %}
{% tab title="Example" %}
```json
{
"projects": [
{
"project_id": "003ksr13jstw0zcq8g",
"vintages": [
{
"vintage_id": "0049zfm3m2vbnpxacv",
"wallets": [
{
"type": "CAAS",
"quantity_grams": "999970",
"trades": [
{
"execution_date": "2023-08-16T11:16:00.643Z",
"quantity_grams": "1000000",
"price_cents": "4500",
"type": "BUY"
},
{
"execution_date": "2023-08-16T09:10:12.062Z",
"quantity_grams": "10000000",
"price_cents": "2450",
"type": "SELL"
}
]
}
]
}
]
}
],
"pagination": {
"per_page": 20,
"total_pages": 1,
"total_items": 1,
"current_page": 1,
"previous_page": null,
"next_page": null
}
}
```
{% endtab %}
{% tab title="Schema" %}
```typescript
{
projects: Array<{
project_id: string
vintages: Array<{
vintage_id: string
wallets: Array<{
type: string
quantity_grams: string
trades: Array<{
execution_date: string
quantity_grams: string
price_cents: string
type: 'BUY' | 'SELL'
}>
}>
}>
}>
pagination: {
per_page: number
total_pages: number
total_items: number
current_page: number
previous_page: number
next_page: number
}
}
```
{% endtab %}
{% endtabs %}
{% endtab %}
{% tab title="401: Unauthorized Your API key is unrecognized or inactive" %}
{% tabs %}
{% tab title="Example" %}
```json
{
"statusCode": 401,
"message": "Unauthorized"
}
```
{% endtab %}
{% tab title="Schema" %}
```typescript
{
statusCode: number
message: string
}
```
{% endtab %}
{% endtabs %}
{% endtab %}
{% tab title="403: User does not have `API User` role." %}
{% tabs %}
{% tab title="Example" %}
```json
{
"error": "Forbidden",
"message": "Permission denied according to assigned roles.",
"statusCode": 403
}
```
{% endtab %}
{% tab title="Schema" %}
```typescript
{
statusCode: number
message: string
error: string
}
```
{% endtab %}
{% endtabs %}
{% endtab %}
{% tab title="500: Server error An unexpected error has occurred on the server." %}
{% tabs %}
{% tab title="Example" %}
```json
{
"statusCode": 500,
"message": "Internal server error"
}
```
{% endtab %}
{% tab title="Schema" %}
```typescript
{
statusCode: number
message: string
}
```
{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}
---
# 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://docs.market.thallo.io/api-endpoints/inventory.md?ask=
```
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.