Skip to content

API reference overview

Gib is a token metadata and image engine. This section describes its application programming interface (API). All endpoints are public. You need no authentication, except for a few moderation endpoints that are for the operator only.

Address: every path in this section is relative to the address of your instance, for example https://gib.show, the public instance that the project runs. Every path works the same on any instance. To run your own, see Self-hosting. The examples use https://gib.show so that you can copy them.

The endpoint reference is built from the server’s OpenAPI definition. It lists every path, parameter and response, and it always matches the running code. The pages in this section explain how the endpoints behave and why. Read them together.

Every endpoint that takes a chain accepts two forms:

  • The prefixed identifier, such as eip155-369.
  • The bare number, such as 369. Bare numbers work for Ethereum-style (eip155) chains.

Chains that are not Ethereum-style, such as Solana and Tron, need the prefixed form. Chain 0 uses the asset namespace (asset-0).

Algorand answers to its ARC-25 chain numbers 4160 (the older number, for all Algorand chains) and 416001 (MainNet). You can write them bare or as eip155-4160 and eip155-416001. All of them resolve to algorand-283. The ARC-25 TestNet and BetaNet numbers (416002, 416003) are not served.

Responses that name a chain give both forms. For example, /networks and /stats return chainId as a bare number and chainIdentifier as the prefixed form.

Page What it covers
Images Token images, network images, images by hash, fallback and batch lookup
Image options Resize, format, filters, licence filter, response headers
Image priority How Gib picks one image when many providers have one
Token lists The list index, single lists, versions, ranked tokens per chain, merged lists
Search Find tokens by name, symbol or address
Networks Supported networks and chains
Statistics Token counts per chain
Sprite sheets Many small images in one request
Submissions Send in a token list or an image
Service endpoints Health, the OpenAPI definition, guides and terms
Caching Cache lifetimes and how to cache well
Rate limits What is and is not limited
Integration examples React, HTML and recommended sizes

Errors are JSON objects with one error field that holds a message. The status codes are the usual ones: 400 for a bad request, 401 for a missing admin token, 404 when nothing matches, 406 for an unsupported format, and 503 while the server starts.