Skip to content

Token image with an explicit provider ordering

GET
/image/{order}/{chainId}/{address}
curl --request GET \
--url 'https://gib.show/image/example/eip155-369/0xA1077a294dDE1B09bB078844df40758a5D0f9a27?only=vector&license=MIT&mode=link&as=webp&format=webp&bg=ffffff&shape=circle&contrast=dark'

An unknown order name silently falls back to the default ordering.

order
required
string

Named ordering (e.g. default) or order id.

chainId
required
string

Chain identifier — prefixed form (eip155-369) or bare numeric (369). Chain 0 uses the asset namespace (asset-0). Algorand ARC-25 ids 4160 and 416001 (bare or eip155-) are aliases of algorand-283.

address
required
string

Token contract address (checksummed or lowercase).

only
string
Allowed values: vector raster

Filter source images by type before selection. With only=vector the answer is an SVG source or 404, never a raster image. A network has one stored icon, so /image/{chainId}?only=vector answers 404 when that icon is not a vector.

providerKey
string

Comma-separated provider slugs to restrict image sources.

listKey
string

Comma-separated list slugs to restrict image sources.

license
string

Opt-in licence allowlist, matched case-insensitively (repeatable or comma-separated, e.g. ?license=MIT&license=Apache-2.0). When present, only candidates whose EFFECTIVE licence — the list entry’s own, verified against where its image actually lives, never a provider’s licence by default — is in this set are considered, and the best-ranked one among them is served. A licence gib.show has not verified is unknown, not permitted, so it never matches this filter. When no candidate qualifies the response is the ordinary 404 for this route, never an unlicensed image.

mode
string
Allowed values: link

Mode=link responds 302 to the original source URI instead of serving content.

as
string
Allowed values: webp png jpg jpeg avif

Convert output format. Requesting svg succeeds when the stored image already is one and is served unchanged; against a raster source it returns 404, because a raster image cannot be converted to a vector one. Every other unrecognised value is ignored and the original format is served.

format
deprecated
string
Allowed values: webp png jpg jpeg avif

Deprecated alias for as, kept because an earlier version of the published documentation named the output-format parameter format. Prefer as; when both are present as wins.

w
integer
>= 1 <= 2048

Resize width in pixels (1-2048), fit inside, never enlarged.

h
integer
>= 1 <= 2048

Resize height in pixels (1-2048), fit inside, never enlarged.

bg
string
/^([0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/

Paint a plate of this colour behind the logo: 3, 6 or 8 hex digits without #, the last two of eight being alpha (for example ffffff, f80, 00000080). Any other value answers 400. A vector image stays a vector (image/svg+xml) unless as asks for pixels. With as=svg, a vector image that has no usable viewBox cannot take a plate as a vector, and the answer is 404 and not a png. A plate drawn to pixels is never wider than 2048 pixels: a larger logo is shrunk to fit. With contrast as well, bg is the plate colour and contrast decides whether the plate appears.

shape
string
default: circle
Allowed values: circle rounded square

The outline of the plate. Only used together with bg or contrast; on its own it is checked and then ignored. Any other value answers 400.

contrast
string
Allowed values: dark light

Say whether your page is dark or light. Gib looks at what share of the visible pixels of the logo have at least 3:1 contrast with that page, and adds a plate in the opposite tone (light on dark, dark on light) only when that share is under 25 percent, so a logo with some strong parts is left alone. Otherwise the image is served as if the parameter were absent. If the logo cannot be measured, the plain image is sent with cache-control: no-store. Any other value answers 400.

Image content. Headers: cache-control (public, max-age=86400 with a seven-day stale-while-revalidate and stale-if-error window; year-long immutable for a raster image at /image/direct/{hash}; a vector image there uses the ordinary lifetime), x-resize (original or variant), x-uri (source when known). Every image response also carries content-security-policy (default-src ‘none’; img-src data:; style-src ‘unsafe-inline’; sandbox) and x-content-type-options: nosniff, so an image opened directly in a browser cannot run a script. A request that carries plate parameters (bg, shape or contrast) always uses the shorter lifetime, on every route, even when no plate was needed, because its answer depends on how Gib draws plates. When a plate was asked for and could not be produced (the logo cannot be measured or drawn), the plain image is sent with cache-control: no-store.

Media type: image/*
string format: binary

Redirect to the original source URI (mode=link).

No matching image.

Media type: application/json
object
error
string

Example generated

{
"error": "example"
}

Plated images (bg or contrast) are drawn on demand and never stored, so each image has an allowance of 30 per minute, each caller 120 and the whole service 600. A caller is named by its network address, or by the address a trusted proxy reports; behind a proxy that cannot be told apart, only the other two apply. A linked image is not downloaded for a refused request. Retry-After says how long to wait (60 seconds); the answer is never cached.

Media type: application/json
object
error
string

Example generated

{
"error": "example"
}

Too many plated images are being drawn at once, or this caller already has four waiting. Retry-After says how long to wait (2 seconds); the answer is never cached. Plain images, resizes, and requests that need no plate are not affected.

Media type: application/json
object
error
string

Example generated

{
"error": "example"
}