Skip to main content
Version: v1.7.0

Maestro dApp Platform API

Maestro follows the REST Web API architecture. See details below.

Specific API references​

ServiceAPI Reference
Blockchain IndexerAPI Reference
Transaction ManagerAPI Reference
Managed ContractsAPI Reference
DeFi Market APIAPI Reference
Wallet ManagerAPI Reference
tip

What's new?

Checkout API Change Log for recently added and deprecated endpoints

Cardano Networks​

The Maestro API is available for all Cardano networks using the following base URLs:

NetworkBase URL
Mainnethttps://mainnet.gomaestro-api.org/v1
Pre-Productionhttps://preprod.gomaestro-api.org/v1
Previewhttps://preview.gomaestro-api.org/v1

API Versions​

The Blockchain Indexer API is currently versioned at v1. When making a query, v1 must be included in your base URL.

OpenAPI​

Here is the latest Maestro openapi.json for the Blockchain Indexer API, DeFi Market API and Managed Contracts API. For all other Maestro APIs please refer here.

SDK Language Support​

The following SDKs are available:

  • Haskell
  • Typescript
  • Go
  • Rust
  • Python
info

Explore Maestro's SDKs

Authentication​

Maestro API authorizes requests using the api-key header. You can obtain this key from the Dapp Platform Dashboard as described here.

Example GET request for retrieving the chain tip:

curl -X GET \
    -H "api-key: <your_project_api_key>" \
    https://mainnet.gomaestro-api.org/v1/chain-tip

Example POST request for submitting a transaction:

curl -X POST \
    -H "Content-Type: application/cbor" \
    -H "api-key: <your_project_api_key>" \
    --data @tx.signed \
    https://mainnet.gomaestro-api.org/v1/submit/tx

Security​

Ensuring secure communication between your Application and Maestro is paramount. This will enforce access control to your Maestro resources.

caution
  • Do not share your api-key in publicly accessible areas such as GitHub, client-side code, etc.
  • Loss or misuse of your api-key may result in the overuse of your account's available credits.
  • We encourage you to research how to securely store and access your api-key either while testing or in production.

Cursor-based pagination​

Some Maestro endpoints implement cursor-based pagination to break down large datasets into smaller responses. This method is particularly relevant when returning all the data in a single response would be impractical or slow.

Benefits of Cursor-based pagination
  • Better data integrity and accuracy when fetching multiple pages
  • Avoids duplicates when blocks get processed between queries
  • Works well with infinite scroll. Loading content as the user scrolls, for a smoother UX.

These Maestro responses will include a next_cursor string property indicating the value that should be included as cursor string in your next request to fetch the next page.

Example
  • Using endpoint UTxOs containing assets of policy.
  • If the response for an initial call ended in "next_cursor": "AAAAAALfeKF8btdzaVvkGaetSS7e1AAF"
  • The next call could include that value as Query Parameter cursor
  • By adding ...?cursor=AAAAAALfeKF8btdzaVvkGaetSS7e1AAF to the end of the query
  • Resulting in the endpoint returning the next page of results
curl -L -X GET 'https://mainnet.gomaestro-api.org/v1/policy/f0ff48bbb7bbe9d59a40f1ce90e9e9d0ff5002ec48f232b49ca0fb9a/utxos?cursor=AAAAAALfeKF8btdzaVvkGaetSS7e1AAF' \
-H 'Accept: application/json' \
-H 'api-key: your-api-key'

When a response presents next_cursor of null then the end of the requested dataset has been reached.

Other relevant Query Parameters are:

ParameterDefaultDescription
count100Defines the max number of results per pagination page
orderascThe order in which the results are sorted. Possible values: [asc, desc]. Only for some endpoints.

Our specific REST API References may include further detail for a specific endpoint.

Compute Credits​

Compute Credits is how Maestro quantifies the computational resources utilized by your applications on its platform. They function similar to compute usage on traditional cloud providers like Google Cloud and AWS. The quantity of Compute Credits assigned to each operation or method is calculated based on the global average durations of that method, accounting for factors like complexity and computational intensity.

Learn more about how compute credits are allocated for different API packages in the Subscriptions breakdown.

info

Why use Compute Credits?

Compute Credits offer a fair and flexible pricing model on Maestro's platform. Developers only pay for the exact computational resources they have used, enhancing efficiency and cost-effectiveness.

Request Limits​

Two types of API request rate limits are enforced:

  • Per day: a set amount of credits consumed per day based on the package tier.
  • Per second: a set amount of requests per second based on the package tier.
note

The base throughput request limit found in the Artist plan is 10 requests per second.

Please see the available Packages for more details or to upgrade your plan. If these limits are insufficient for your organization, please reach out to us to discuss Enterprise solutions.

Response Headers​

The following elements are included in the response headers from Maestro:

  • X-RateLimit-Limit-Second: number of allowed requests per second
  • X-RateLimit-Remaining-Second: number of allowed requests per second remaining in this second
  • X-Maestro-Credits-Limit: number of allowed credits today
  • X-Maestro-Credits-Remaining: number of allowed credits remaining today

Please make sure to consider these (in bold) and throttle requests to avoid get rate limiting.

Errors​

Maestro returns conventional HTTP response codes to indicate the success or failure of an API request:

  • Codes in the 2xx range indicate success.
  • Codes in the 4xx range indicate an error that occurred given the query parameters or request payload (e.g. required parameter was omitted).
  • Codes in the 5xx range indicate an error with Maestro's servers.

Our specific REST API References describe response codes for each endpoint in more detail.

Ongoing deprecations​

  • From v1.4.5
    • Deprecated /epochs/{epoch_no}/info
    • Will remain functional until Jan 15th, 2023
    • Please use improved /epochs/{epoch_no} instead

Change Log​

v1.7.0​

ADDED Direct Swap Contract on Managed Contracts API

v1.6.3​

v1.6.2​

v1.6.1​

v1.6.0​

  • REMOVED previously deprecated endpoints
    • From v1.4.3:
      • /datum/{datum_hash}
    • From v1.4.1:
      • /assets/policy/{policy}
      • /assets/policy/{policy}/accounts
      • /assets/policy/{policy}/addresses
      • /assets/policy/{policy}/txs
      • /assets/policy/{policy}/utxos
      • /assets/{asset}/txs
      • /assets/{asset}/updates

v1.5.8​

v1.5.7​

v1.5.6​

v1.5.5​

v1.5.4​

  • UPDATED /transactions/outputs Transaction outputs by output references
    • Added an allow_missing parameter to not return 404 if any output references are not found

v1.5.3​

v1.5.2​

v1.5.1​

Updated DeFi Market API - Now out of Beta!

v1.4.5​

  • NEW /blocks/latest Latest block information
    • Returns information about the most recently minted block
  • DEPRECATED /epochs/{epoch_no}/info
    • Will remain functional until Jan 15th, 2023
    • Please use improved /epochs/{epoch_no} below
  • NEW /epochs/{epoch_no} Specific epoch details
    • Replaces deprecated /epochs/{epoch_no}/info
    • Adds active_stake: Total active stake for the epoch
    • Adds total_rewards: Total rewards earned by block producers during the epoch
    • Adds average_reward: Average reward for block producers during the epoch

v1.4.4​

  • UPDATED Added amounts-as-strings optional header parameter for several endpoints

v1.4.3​

Payment Credentials

Datums

v1.4.2​

  • Removed vesting memo param from Linear Vesting endpoint

v1.4.1​

info

Deprecated endpoints will remain functional until Nov 30th, 2023. Removed Feb 16th 2024.

Breaking Change

Updated endpointsChanges
Native asset information
/assets/{asset}		Removed: first_mint_time moved into first_mint_tx as timestamp
Breaking change: first_mint_tx additional transaction details (amount, timestamp, hash)
New: latest_mint_tx same transaction details from first_mint_tx
New: unique_holders number of holders by_account and by_address

New & Deprecated Policy endpoints

Deprecated endpointsCorresponding or New endpoints
Information on assets of specific policy
/assets/policy/{policy}		Information about a policy of native assets
/policy/{policy}
Accounts of addresses holding assets of specific policy
/assets/policy/{policy}/accounts		Accounts of addresses holding assets of specific policy
/policy/{policy}/accounts
Addresses holding assets of specific policy
/assets/policy/{policy}/addresses		Addresses holding assets of specific policy
/policy/{policy}/addresses
Transactions moving assets of specific policy
/assets/policy/{policy}/txs		Transactions involving assets of policy
/policy/{policy}/transactions
UTxOs containing assets of specifc policy
/assets/policy/{policy}/utxos		UTxOs containing assets of specific policy
/policy/{policy}/utxos
List assets of policy
/policy/{policy}/assets
Transactions minting or burning assets of policy
/policy/{policy}/mints

New & Deprecated Asset endpoints

Deprecated endpointsCorresponding or New endpoints
Native asset transactions
/assets/{asset}/txs		Native asset transactions
/assets/{asset}/transactions
Native asset updates
/assets/{asset}/updates		Native asset mints and burns
/assets/{asset}/mints
Accounts of addresses holding specific asset
/assets/{asset}/accounts
Native asset addresses
/assets/{asset}/addresses
Native asset UTxOs
/assets/{asset}/utxos

v1.3.3​

v1.3.2​

v1.3.1​

Added DeFi Market API

v1.2.1​

Added Wallet Manager API

v1.1.1​

Added Managed Contracts API

v1.0.18​