time	status	user agent
Retrieving recent requests…

time

status

user agent

Retrieving recent requests…

Benefits Endpoint Examples

The Benefits endpoint allows you to retrieve a list of benefits supported by the Miracle API Protocol. These benefits can include airdrops, event tickets, exclusive content, and more, associated with specific NFT collections across different chains. This endpoint includes all benefits gathered from sources coming from Official, Third Party, and Community Sources.

Important Notes

validFrom and validTo:
- validFrom: The date when the benefit becomes active and trackable on the Miracle.
- validTo: The date when the benefit expires and is no longer available.
Action Date:
- Represents the deadline for the user to take a specific action, such as claiming or minting a benefit.
- May differ from validTo in cases like events where tickets need to be claimed by a certain date (actionDate), but the event occurs later (validTo).

Enhancing Your Product with Benefits

By leveraging the Benefits endpoint, you can enhance your web3 applications in various ways:

New Benefits Feed: Display the latest benefits added.
Last Chance: Highlight benefits that are expiring soon, creating urgency.
Collection Highlights: Showcase benefits associated with specific NFT collections.
Personalized Experiences: Present benefits available to individual users based on their wallet holdings.

Thumbnail Guidelines

For optimal visual presentation across various devices and interfaces, we advise using a 16:9 thumbnail ratio for all benefit visuals. This recommended ratio ensures:

Optimal Fit: Thumbnails render properly on different screen sizes including desktop, tablet, and mobile devices.
Consistent Appearance: Maintaining a standard 16:9 aspect ratio across your application helps preserve a unified and professional look.
Enhanced User Experience: A predictable and balanced thumbnail size boosts visual clarity and focus, especially when displaying multiple benefits.

Examples

New Benefits Feed

Display the most recently added benefits:

Request:

curl GET "https://www.themiracle.io/api/v1/benefits?sortBy=validFrom&sortDirection=DESC&limit=20"

New Benefits Feed

Display the most recently added benefits:

Request

curl GET "https://www.themiracle.io/api/v1/benefits?sortBy=validFrom&sortDirection=DESC&limit=20"

Explanation

sortBy=validFrom: Sorts benefits by the date they became active.
sortDirection=DESC: Displays the newest benefits first.
limit=20: Returns up to 20 benefits.

Last Chance

Show benefits that are expiring soon:

Request

curl GET "https://www.themiracle.io/api/v1/benefits?sortBy=validTo&sortDirection=ASC&limit=20"

Explanation

sortBy=validTo: Sorts benefits by their expiration date.
sortDirection=ASC: Displays benefits that will expire soonest.
limit=20: Returns up to 20 benefits.

200

xxxxxxxxxx
curl --request GET \
     --url 'https://www.themiracle.io/api/v1/third-party/benefits?limit=20&offset=0' \
     --header 'accept: application/json' \
     --header 'x-api-key: b7aa19fe-b26b-4cb7-b165-cf0ae8bb77c3'

xxxxxxxxxx
}
{
  "longTitle": "Using the Magisat Tool for Optimal UTXO Management",
  "longDescription": "Follow these steps to manage your Ordinals and UTXOs effectively on Magisat, including exclusive benefits for AOG holders.\n\n- Go to magisat.io and connect your wallet via the button in the top-right corner.\n- Navigate to \"My Items\" and select the \"Inscriptions\" tab (or \"Runes\" tab if applicable).\n- Review items with a UTXO size over 5,000 sats or any in BTC denomination (last column).\n- Select the items, then click \"Isolate UTXO\" to separate larger UTXOs.\n- The tool will recommend an ideal split, ensuring Ordinals remain in 546-sat UTXOs and common sats are set to the payment address (automated for Xverse or Phantom users).\n\nWith a 12k sats base fee, free at least 20k sats per transaction for cost-efficiency. AOG holders receive a lifetime discount on Magisat actions.",
  "thumbnail": "https://pbs.twimg.com/media/GcJHdWzXMAAZaVR?format=jpg&name=medium",
  "validFrom": "2024-11-12T00:00:00+00:00",
  "validTo": "2030-12-31T00:00:00+00:00",
  "url": "https://magisat.io/",
  "location": "Online",
  "actionDate": "2030-12-31T00:00:00+00:00",
  "process": "Check it out",
  "collections": [
    {
      "name": "Apostles of Greed",
      "contractAddress": "8a8844b2b18daf9e4127787a6ca1a493d0fb8072138d7150261fe397dc0beaeai0",
      "chain": "bitcoin",
      "url": "https://www.themiracle.io/collections/1353",
      "contractSlug": "aog-orange"
    }
  ],
  "official": false,
  "timeZone": null,
  "categories": [
    {
      "name": "Lifestyle"
    }

Benefits Endpoint Examples

Important Notes

Enhancing Your Product with Benefits

Thumbnail Guidelines

Examples

New Benefits Feed

New Benefits Feed

Request

Explanation

Last Chance

Request

Explanation

200200

400400