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. 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.

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>

Quick links