Developer Docs

Experimental API Notice

The current API structure represents the initial public release of the RANNTA developer platform. Some endpoints are active, some are partially connected, and others are reserved for the staged production rollout.

Authentication, quotas, and response formats may evolve during the testing phase.

RANNTAverse API documentation overview

This page lists route handlers that exist in the current app. Some routes are conditional because they proxy a relayer or an external TON provider, and API key enforcement is staged through the developer access helper.

Base URL

https://ranntaverse.app

Current routes are exposed under the Next.js app API namespace. A separate /v1 gateway is not implemented in this repository yet.

Authentication

X-API-Key: rnt_live_...

API key hashing, admin-gated issuance, validation, and daily usage tracking now exist. Free signup requires a TON wallet signature. Protected Developer facade routes validate scopes while existing Warp, Forge, registry, and Jetton routes remain public for current app flows.

Protected quote facade

curl -H "X-API-Key: rnt_live_..." \
  "https://ranntaverse.app/api/developers/warp/quote?direction=TON_TO_ETH&assetId=rannta&amount=1&payAsset=RANNTA"

The response includes productFamily, endpointKey, scope, source, freshness, relayerStatus, quotaRemaining, fetchedAt, and data.

Free wallet signup

POST /api/developers/signup
{
  "email": "dev@example.com",
  "displayName": "Example Developer",
  "walletAddress": "EQ...",
  "signature": {
    "type": "tonconnect-sign-data",
    "signature": "...",
    "address": "EQ...",
    "timestamp": 1775960000,
    "domain": "ranntaverse.app",
    "publicKey": "...",
    "walletStateInit": "...",
    "payload": {
      "type": "text",
      "text": "RANNTA Developer Signup: EQ..."
    }
  }
}

The signed message is RANNTA Developer Signup: <walletAddress>. The raw API key is returned once; only the SHA-256 hash is stored.

Operator key issuance

curl -X POST "https://ranntaverse.app/api/developers/keys" \
  -H "Content-Type: application/json" \
  -H "X-Developer-Admin-Key: $DEVELOPER_KEY_ISSUER_SECRET" \
  -d '{"displayName":"Sandbox key","ownerEmail":"dev@example.com","planKey":"free","scopes":["quote:read","status:read","registry:read"]}'

This route requires DATABASE_URL and DEVELOPER_KEY_ISSUER_SECRET. The raw key is returned once; only the SHA-256 hash is stored.

Current endpoints

GET/api/adapter/assetslive

Lists relayer-backed bridge assets.

Live as a legacy public route when RELAYER_BASE_URL is configured.

Legacy route remains public for existing Warp UI flows.

Source: relayer; freshness: live_backend; product family: registry

GET/api/adapter/quote?direction=TON_TO_ETH&assetId=rannta&amount=1&payAsset=RANNTAlive

Returns relayer-backed quote data for Warp flows.

Live as a legacy public route when RELAYER_BASE_URL is configured.

Legacy route remains public for existing Warp UI flows.

Source: relayer; freshness: live_backend; product family: warp

POST/api/adapter/create-intentbeta

Creates a relayer intent for Warp execution.

Live when RELAYER_BASE_URL is configured.

Public route today; payload contract stays owned by the relayer.

Source: relayer; freshness: live_backend; product family: warp; scopes: intent:create

GET/api/adapter/status/{messageId}live

Checks relayer status for a Warp message.

Live as a legacy public route when RELAYER_BASE_URL is configured.

Legacy route remains public for existing Warp UI flows.

Source: relayer; freshness: live_backend; product family: warp

POST/api/registry/applybeta

Stores Warp listing applications in Postgres through Drizzle.

Live when DATABASE_URL is configured.

Public application route today; admin review is separately protected.

Source: database; freshness: database; product family: registry

GET/api/forge/registrybeta

Reads Forge token registry records from Postgres.

Live when DATABASE_URL is configured.

Public route today; developer key validation helper is available for gated rollout.

Source: database; freshness: database; product family: registry; scopes: registry:read

POST/api/forge/metadatabeta

Creates reusable Forge metadata records in Postgres.

Live when DATABASE_URL is configured.

Public route today; developer key validation helper is available for gated rollout.

Source: database; freshness: database; product family: registry

GET/api/jetton/balance?wallet=UQ...live

Reads Jetton balances through Tonapi.

Live with Tonapi public access; TONAPI_KEY can improve provider access.

Public route today; upstream provider limits still apply.

Source: tonapi; freshness: external_provider; product family: verification

GET/api/jetton/inspect?address=EQ...live

Inspects Jetton master data through Toncenter.

Live with Toncenter public access; TONCENTER_API_KEY can improve provider access.

Public route today; upstream provider limits still apply.

Source: toncenter; freshness: external_provider; product family: verification

POST/api/developers/keysinternal

Issues hashed RANNTAverse developer API keys through an admin-gated route.

Live when DATABASE_URL and DEVELOPER_KEY_ISSUER_SECRET are configured.

Requires X-Developer-Admin-Key.

Source: local; freshness: internal_only; product family: developers_core

POST/api/developers/signuplive

Issues a free developer API key through TON wallet signature signup.

Live when DATABASE_URL is configured and wallet_address exists on developer_api_keys.

Requires email, displayName, walletAddress, and a valid TON wallet signature.

Source: local; freshness: database; product family: developers_core

GET/api/developers/meprotected

Validates a developer API key and records a usage event.

Live when DATABASE_URL is configured and a developer API key exists.

Requires X-API-Key.

Source: local; freshness: database; product family: developers_core

GET/api/developers/my-keyprotected

Returns plan, quota, and scopes for the provided developer API key.

Live when DATABASE_URL is configured and a developer API key exists.

Requires X-API-Key.

Source: local; freshness: database; product family: developers_core

GET/api/developers/wallet-statusprotected

Returns the wallet binding, plan, and quota for the provided developer API key.

Live when DATABASE_URL is configured and a wallet-bound developer API key exists.

Requires X-API-Key.

Source: local; freshness: database; product family: developers_core

GET/api/developers/billing/quote?planKey=builder&payAsset=TONprotected

Creates a production TON mainnet wallet-bound payment intent quote with treasury routing and memo binding.

Live for production TON mainnet only when DATABASE_URL, DEVELOPER_TREASURY_TON_ADDRESS, and manual conversion rates are configured.

Requires X-API-Key. The payment intent is bound to the key wallet address.

Source: database; freshness: database; product family: developers_core

GET/api/developers/billing/status/{intentId}protected

Returns the lifecycle state for a developer billing payment intent owned by the API key.

Live when DATABASE_URL is configured and the payment intent exists.

Requires X-API-Key for the key or wallet that owns the intent.

Source: database; freshness: database; product family: developers_core

POST/api/internal/developers/billing/processinternal

Internal worker trigger for TON and RANNTA mainnet payment verification and plan activation.

Internal only; requires DEVELOPER_BILLING_WORKER_SECRET and TON mainnet provider configuration.

Requires X-Developer-Billing-Worker-Secret.

Source: toncenter; freshness: external_provider; product family: developers_core

GET/api/developers/warp/quote?direction=TON_TO_ETH&assetId=rannta&amount=1&payAsset=RANNTAprotected

Protected relayer-backed quote facade with usage metering.

Live when RELAYER_BASE_URL, DATABASE_URL, and a scoped API key are configured.

Requires X-API-Key with quote:read.

Source: relayer; freshness: live_backend; product family: warp; scopes: quote:read

GET/api/developers/warp/status/{messageId}protected

Protected relayer-backed Warp message status facade with usage metering.

Live when RELAYER_BASE_URL, DATABASE_URL, and a scoped API key are configured.

Requires X-API-Key with status:read.

Source: relayer; freshness: live_backend; product family: warp; scopes: status:read

GET/api/developers/registry/assetsprotected

Protected relayer-backed bridge asset registry facade with usage metering.

Live when RELAYER_BASE_URL, DATABASE_URL, and a scoped API key are configured.

Requires X-API-Key with registry:read.

Source: relayer; freshness: live_backend; product family: registry; scopes: registry:read

Onboarding

Confirm the endpoint you need is listed as live or protected.
Use /api/developers/signup for a free key with TON wallet verification.
Send X-API-Key when using protected Developer facade routes.
Keep relayer and TON provider configuration aligned with the route you call.

Not implemented yet

Public /v1 gateway routes
Live subscription billing
Webhook delivery
SLA-backed enterprise access