API Usage

authentication you will need an api key to access the maestro api you can obtain this key from the maestro dapp platform dashboard examples get request example get request for retrieving the chain tip curl x get \\ h "api key \<your project api key>" \\ https //xbt mainnet gomaestro api org/v0/chain tip post request example request for submitting a transaction curl x post \\ h "content type application/cbor" \\ h "api key \<your project api key>" \\ \ data @tx signed \\ https //xbt mainnet gomaestro api org/v0/submit/tx security to ensure the security of your api usage, follow these best practices keep your api key private never share it publicly (e g , on github, client side code) prevent unauthorized usage loss or misuse of your api key can result in the overuse of your account's available credits secure your api key implement proper methods for storing and accessing your api key , especially in production environments cursor based pagination ​ https //docs gomaestro org/bitcoin/intro#cursor based pagination some maestro endpoints use cursor based pagination to break large datasets into smaller, more manageable responses this method is particularly relevant when returning all the data in a single response would be inefficient or slow improved data integrity and accuracy when fetching multiple pages prevents duplicates , even when new blocks are processed between queries optimized for infinite scroll , enabling a smooth user experience by loading content as the user scrolls when using this method, responses will include a next cursor string this value should be passed as the cursor parameter in your next request to retrieve the next page of results example initial response when you make an initial api call, the response might include a "next cursor" "aaaaaalfekf8btdzavvkgaetss7e1aaf" this indicates that there are more results to retrieve using next cursor to get the next page of data, you need to include the next cursor value in your next api request by adding it as a query parameter ( cursor ) modifying the query append the cursor value to your api request url, like this ?cursor=aaaaaalfekf8btdzavvkgaetss7e1aaf result the api will return the next set of results when this value is provided end of data if the response includes "next cursor" null , the requested dataset's end has been reached other relevant query parameters are parameter default description count 100 defines the maximum number of results per pagination page order asc specifies the sort order of the results acceptable values are asc (ascending) or desc (descending) this option is available only for specific endpoints example 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' available https //documentation gomaestro org/ will include further details for a particular endpoint computer credits maestro uses compute credits to measure the computational resources consumed by your applications on its platform, similar to traditional cloud providers like google cloud or aws the number of credits assigned to each operation or method is based on the global average duration of that process, taking into account factors like complexity and computational intensity learn more about how compute credits are allocated by exploring the subscription breakdown \[insert link] compute credits provide a fair, usage based pricing model , meaning you only pay for the computational resources your application actually uses, making it both cost efficient and flexible request limits maestro enforces two types of api rate limits per day a set amount of credits consumed per day based on your subscription https //www gomaestro org/pricing plan per second a set amount of requests per second based on your subscription https //www gomaestro org/pricing plan for example, the artist plan supports up to 10 requests per second for more details on available packages or to upgrade your plan, refer to the pricing page https //www gomaestro org/pricing https //www gomaestro org/pricing if your organization needs higher limits, contact us mailto\ info\@gomaestro org to discuss enterprise solutions response headers maestro includes the following headers in api responses to help manage usage header description x ratelimit limit second maximum allowed requests per second x ratelimit remaining second remaining allowed requests for the current second x maestro credits limit total allowed credits for the day x maestro credits remaining remaining credits for the day be sure to monitor these values (in bold ) and adjust your request rate accordingly to avoid hitting rate limits errors maestro follows standard http response codes to indicate the success or failure of api requests 2xx success 4xx client side errors, such as missing or incorrect parameters 5xx server side errors with maestro refer to the api reference docid\ a9 3xokti0ljmco7jmpql or detailed response codes for each endpoint