This article will guide you on how to use the Magic Eden Bitcoin Ordinals API to gather data for your applications.
API endpoints
Clusters
Mainnet:
api-mainnet.magiceden.dev/v2/ord- This endpoint provides access to the real Ordinals Mainnet cluster, where the tokens are real and the data is consistent with what you see on https://magiceden.io/ordinals (Please note that US users will be redirected to https://magiceden.us/ordinals)
Ordinals API keys
To access certain endpoints, you may need an API key. The API key is required to authorize your HTTP requests.
Rate limiting
The public API is free to use, and the default rate limit is 30 queries per minute (QPM). Unauthorized requests use the "demo" key, which is also subject to the 30 QPM limit. Please note that exceeding the rate limit may result in a 429 status code. If you require a higher limit, please fill out the form to obtain an API key.
When making batch requests, it is recommended to add a small timeout between requests to avoid connection refusal, regardless of whether you have an API key or not.
Authorization header
To access the instruction endpoints, you must include an Authorization header in your HTTP requests. The value of the Authorization header should be Bearer followed by your API key.
Example:
makefileCopy codeAuthorization: Bearer YOUR_API_KEY
Replace YOUR_API_KEY with the actual API key provided to you.
Endpoints
Get collection
Method: GET
Endpoint:
https://api-mainnet.magiceden.dev/v2/ord/btc/collections/{symbol}Description: Retrieve information about a specific collection.
Path Parameters:
symbol(required): The symbol of the collection.
Response:
200: Successful response
Get collection stats
Method: GET
Endpoint:
https://api-mainnet.magiceden.dev/v2/ord/btc/statDescription: Retrieve statistics about the Bitcoin Ordinals collection.
Query Parameters:
collectionSymbol(required): The symbol of the collection.
Response:
200: Successful response
Get popular collection stats
Method: GET
Endpoint:
https://api-mainnet.magiceden.dev/v2/ord/btc/popular_collectionsDescription: Retrieve statistics about popular collections.
Query Parameters:
window(required): The time window for the statistics. Valid values are1h,6h,1d,7d,30d.limit: The limit on the number of results.
Response:
200: Successful response
Get activities
Method: GET
Endpoint:
https://api-mainnet.magiceden.dev/v2/ord/btc/activitiesDescription: Retrieve activities filtered by collection, kind, token ID, and owner address. By default, the activities are sorted by createdAt in descending order.
Query Parameters:
collectionSymbol: The symbol of the collection to filter.kind: The kind of activity to filter (e.g.,transfer,create,list,delist,buying_broadcasted,mint_broadcasted).tokenId: The ID of the token to filter.ownerAddress: The address of the owner to filter.limit: The limit on the number of results.offset: The offset for pagination.inscriptionMin: The minimum inscription number.inscriptionMax: The maximum inscription number.satRarity: The rarity level of the token (e.g.,common,uncommon,rare,epic,legendary,mythic).
Response:
200: Successful response
Get tokens
Method: GET
Endpoint:
https://api-mainnet.magiceden.dev/v2/ord/btc/tokensDescription: Retrieve tokens filtered by collection, owner, and token IDs.
Query Parameters:
tokenIds: An array of token IDs to filter.collectionSymbol: The symbol of the collection to filter.ownerAddress: The address of the owner to filter.showAll: Boolean value to determine whether to show all items, including listed and unlisted ones.limit: The limit on the number of results.offset: The offset for pagination.inscriptionMin: The minimum inscription number.inscriptionMax: The maximum inscription number.sortBy: The field to sort the results by (e.g.,priceAsc,priceDesc,listedAtAsc,listedAtDesc,inscriptionNumberAsc,inscriptionNumberDesc).minPrice: The minimum price.maxPrice: The maximum price.satRarity: The rarity level of the token (e.g.,common,uncommon,rare,epic,legendary,mythic).
Response:
200: Successful response
If you have any further questions or need assistance, don't hesitate to reach out to us.