Market

Get all of the available sell orders on the market in real-time

Overview

Access the Thallo market data via API. The screenshot below is of the marketplace user interface which shows the same data as this endpoint returns:

Example cURL Request

curl --request GET 'https://${BASE_URL}/api/market?page=1&per_page=20' \
--header 'Authorization: Bearer ${API_KEY}'

Endpoint Specification

Get market data

GET /api/market

Get all of the available sell orders on the market in real-time

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.

Headers

Name	Type	Description
Authorization*	string	Bearer ${API_KEY}

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.

Example

{
    "projects": [
        {
            "project_id": "003g3ghxs84jlgw5pi",
            "vintages": [
                {
                    "vintage_id": "004fdpkssx2zi9vodm",
                    "vintage_year": 2019,
                    "sell_orders": [
                        {
                            "sell_order_id": "006mcfdyidljqj9bs1",
                            "quantity_grams": "1000000",
                            "price_cents": "1500"
                        }
                    ]
                }
            ]
        }
    ],
    "pagination": {
        "per_page": 20,
        "total_pages": 5,
        "total_items": 100,
        "current_page": 1,
        "previous_page": 1,
        "next_page": 1
    }
}

Schema

{
    projects: Array<{
        project_id: string
        vintages: Array<{
            vintage_id: string
            vintage_year: number
            sell_orders: Array<{
                sell_order_id: string
                quantity_grams: string
                price_cents: string
            }>
        }>
    }>
    pagination: {
        per_page: number
        total_pages: number
        total_items: number
        current_page: number
        previous_page: number
        next_page: number
    }
}

401: Unauthorized Your API key is unrecognized or inactive

Example

{
    "statusCode": 401,
    "message": "Unauthorized"
}

Schema

{
    statusCode: number
    message: string
}

403: User does not have `API User` role.

Example

{
    "error": "Forbidden",
    "message": "Permission denied according to assigned roles.",
    "statusCode": 403
}

Schema

{
    statusCode: number
    message: string
    error: string
}

500: Server error An unexpected error has occurred on the server.

Example

{
    "statusCode": 500,
    "message": "Internal server error"
}

Schema

{
    statusCode: number
    message: string
}

Enriching With Project Data

The market data changes frequently and this endpoint returns the up-to-date market data upon each call. However the data about the carbon offset projects remains relatively static and therefore this data is available in a separate Project Details endpoint in order to keep the market data endpoint lightweight.

Use the project_ids returned in the market data and call the Project Details endpoint to retrieve the details of each project.

Thallo recommend you cache this project data locally to speed up your application and reduce unnecessary traffic.