• Reading the docs…
Start trading

API reference

Ring destinations

Classifies an Exit destination before the Exit is sealed: an ordinary address, a registered Helius Ring recipient, or unknown.

Route#

GET /v1/rings/{address}#

The Account page’s Exit form checks a destination with it, and exit checks every Ring destination with it before sealing. A Ring Exit goes ahead only to a ring-deposit whose Ring accepts the asset, through acceptsAnyAsset or the mint in acceptedMints; otherwise exit answers VALIDATION_ERROR or ASSET_UNSUPPORTED and seals nothing (Destinations).

The lookup reads Helius’s Ring registry (getUserRecords) through the API’s configured Helius mainnet endpoint. A registry record makes the address a ring-deposit, and no record makes it unknown. The mints a Ring accepts come from the operator’s Ring configuration: with none configured, acceptedMints is empty and reason says so. A Ring recipient is paid with a Ring deposit instruction, never a plain token transfer.

Parameter Type In Meaning
address Address path The destination to classify.

Returns RingLookup.

Errors

  • VALIDATION_ERROR: address is not a base58 address of 32 bytes.
  • CONFIGURATION_REQUIRED: the API has no Helius endpoint for the lookup, or one that is not an https://mainnet.helius-rpc.com URL carrying its api-key.
  • UPSTREAM_UNAVAILABLE: the Ring registry is unreachable, answered invalidly, or answered for another address; retryable.
TypeScript
const target = await api.ring('6dXWnHeZPMqy4ggrrTYYJr7cDSvH6yiV4BgP3y3S3u4T')
const accepts = (mint: string) => target.kind === 'ring-deposit' && target.ring !== null && (target.ring.acceptsAnyAsset || target.ring.acceptedMints.includes(mint))

The answer’s fields are in RingLookup: kind is ring-deposit when Helius holds a Ring record for the address, and unknown when it holds none.

Types#

RingLookup#

Field Type Meaning
address Address The destination looked up.
kind "address", "ring-deposit", "unknown" address for an ordinary destination, ring-deposit for a registered Ring recipient, unknown when the registry holds no record for it, so no Ring is assumed.
ring object or null The Ring, for a ring-deposit; otherwise null.
ring.id string The Ring's id.
ring.name string The Ring's name.
ring.acceptedMints Address[] The mints the Ring accepts, from the operator's Ring configuration; empty until it is set.
ring.acceptsAnyAsset boolean true when the Ring accepts any mint.
ring.transferMode "instruction-required" Paying the Ring takes a Ring deposit instruction, never a plain token transfer.
source "fixture", "helius" helius for Helius's Ring registry, fixture for the local stand-in.
reason string or null Why the destination was classified as it was, when there is more to say; otherwise null.