gotchi.lol API Docs

Use our Sprites API and mini-game embeds in your projects. Sprites are 1:1 character PNGs for Aavegotchis; mini-games are playable HTML you can embed or use as NFT animation_url.

Table of Contents

  1. Sprites API
  2. Mini-Game Embed
  3. Custom Gotchi in games
  4. Usage Examples

Sprites API

Get a PNG image for any summoned Aavegotchi by token ID. Use this URL in games, apps, or embeds.

Endpoint

GET https://gotchi.lol/api/gotchi-sprites/{tokenId}

Example: https://gotchi.lol/api/gotchi-sprites/4895

Response

  • Content-Type: image/png
  • CORS: Enabled (Access-Control-Allow-Origin: *) for cross-origin use
  • Cache: Long-lived cache headers for performance

Errors

  • 404 – Sprite not available (e.g. token not yet generated, or Aavegotchi not summoned)
  • 400 – Invalid token ID

Making sprites available

Sprites are generated and cached when users load them on our site. To ensure a sprite exists for a given token:

  1. Connect your wallet on gotchi.lol/sprites
  2. Click Load My Gotchis to load your collection
  3. Our backend generates and stores sprites for your summoned Aavegotchis

After that, https://gotchi.lol/api/gotchi-sprites/{tokenId} will serve the cached PNG for use in mini-games and other projects.

Mini-Game Embed

Playable mini-games are served as standalone HTML. Use them in iframes or as animation_url in NFT metadata (e.g. OpenSea).

URL format

https://gotchi.lol/api/mini-game/{id}.html

Example: https://gotchi.lol/api/mini-game/1.html

For full mini-game docs (metadata, Phaser, OpenSea compatibility), see Creating Mini Games for NFT Metadata.

Custom Gotchi in games

You can play any mini-game with a specific Aavegotchi by passing the gotchi query parameter with the token ID. Use your own Gotchi or any summoned token ID.

On the site:

  • https://gotchi.lol/games/flapper?gotchi=2729
  • https://gotchi.lol/games/snake?gotchi=2729
  • Same pattern for /games/tower, etc.

In the embed / API HTML:

  • https://gotchi.lol/api/mini-game/1.html?gotchi=2729 (Snake)
  • https://gotchi.lol/api/mini-game/2.html?gotchi=2729 (Tower)
  • https://gotchi.lol/api/mini-game/3.html?gotchi=2729 (Flapper)

Replace 2729 with any summoned Aavegotchi token ID. The game will load that Gotchi’s sprite for the character. If the sprite is not yet cached, load it once via gotchi.lol/sprites (connect wallet and load your Gotchis).

Usage Examples

Use a sprite in HTML

<img src="https://gotchi.lol/api/gotchi-sprites/4895" alt="Aavegotchi #4895" />

Embed a mini-game in an iframe

<iframe
  src="https://gotchi.lol/api/mini-game/1.html"
  title="Gotchi Mini-Game"
  width="400"
  height="600"
></iframe>

Embed with a specific Gotchi

Add ?gotchi={tokenId} to the iframe src to use a custom Aavegotchi in the game:

<iframe
  src="https://gotchi.lol/api/mini-game/3.html?gotchi=2729"
  title="Flapper with Gotchi #2729"
  width="400"
  height="600"
></iframe>

Quick links