Uplift API

Quick start

Base URL: https://uplift.cash/api/v1. Reading token data requires no account, API key, wallet, or cookies. Browser integrations are supported through CORS.

The current deployment is a preview. Responses explicitly include meta.simulated: true. Sample token addresses and payout records do not represent live chain activity.

const base = "https://uplift.cash/api/v1";
const response = await fetch(base + "/tokens?limit=20&currency=USDG");
if (!response.ok) throw new Error("API request failed: " + response.status);
const page = await response.json();

// Both a launch ID and a 0x token address work here.
const token = page.data[0];
const detail = await fetch(base + "/tokens/" + token.address)
  .then(response => response.json());

// Keep exact amounts as strings or convert atomic units to BigInt.
const paid = BigInt(detail.data.payoutStats.totalPaid.atomic);
const asset = detail.data.payoutAsset.symbol;

API discovery returns the environment, limits, and documentation links. Import the OpenAPI 3.1 document into your client generator or API tooling for the complete field schemas.

Token data

Use a 0x address or Uplift l_... launch ID for {token}. Both resolve to the same launch. Public endpoints return launched tokens only; draft reservations require authorization from their creator.

The fees object includes buy and sell creator tax, the treasury recipient, both fee sources, and the holder, operations, and platform-buyback split. Rates use basis points: 500 = 5% and 10,000 = 100%. The sharing split applies after PONS deductions. The standard creator reward rate is null because the API does not currently index that upstream rate.

payoutAsset includes the symbol, official icon URL, chain ID, contract address, and decimals. Native ETH uses the zero address and 18 decimals. USDG uses its Robinhood Chain contract and 6 decimals. Every exact amount includes atomic and decimal strings. Do not convert atomic amounts to JavaScript Number.

Lists accept limit from 1 to 50, defaulting to 20. Pass the returned pagination.nextCursor to fetch another page with the same filters. A null cursor marks the end. Tokens sort by creation time and launch ID, newest first.

Payout evidence

totalFunded is the sum of committed awards. totalPaid includes completed payments. fundedUnpaid is the remaining obligation, while availableForRewards is available for future rounds. Funded awards already reduce a holder’s shortfall even when payment is still outstanding.

Payment records include stable IDs, the round, allocation index, recipient, timestamp, amount, and transaction hash when known. Deduplicate by payment ID when polling. A batch can contain several payments with the same transaction hash. Payments sort by payment time with round and allocation index as tie-breakers. Older records with an unknown payment time appear last.

Poll the first payment page, then continue through its cursors until you reach a previously seen payment. Pagination is not a frozen snapshot across requests; a new payment can arrive while you browse. Allocation pages sort by index and include the proof needed to check inclusion against the round’s root. They cap page size instead of sending an entire large manifest.

Proofs establish inclusion in the published allocation. They do not independently establish the correctness of the price or loss calculation. See payout rules and evidence for the trust model.

Create a launch

Launch creation requires the creator’s wallet signature. No platform account or API key is needed. The API issues a single-use challenge valid for 5 minutes, then a revocable Bearer token valid for 15 minutes. Initially, signatures from externally owned wallets are supported; contract-wallet signature validation is not yet available.

The wallet signature authorizes launch-reservation management. The creator’s wallet separately signs every blockchain transaction. Uplift never asks for a private key, signs for the creator, or broadcasts the returned transaction requests.

// 1. Request a challenge for the creator's wallet.
POST /api/v1/auth/challenge
{ "wallet": "0x..." }

// 2. Sign the exact returned message with personal_sign.
// Confirm its domain, chain ID, environment, and expiration.
POST /api/v1/auth/verify
{ "nonce": "...", "signature": "0x..." }

// 3. Keep accessToken in memory and reserve the launch.
POST /api/v1/launches
Authorization: Bearer <accessToken>
Idempotency-Key: terminal-launch-2026-001
Content-Type: application/json

{
  "simulate": true,
  "token": {
    "name": "Example token",
    "symbol": "EXAMPLE",
    "description": "",
    "website": "",
    "twitter": "",
    "telegram": "",
    "currency": "USDG",
    "taxBps": 500
  }
}

Creator tax defaults to 500 basis points and accepts integers from 10 to 1,000, equivalent to 0.1% through 10%. For example, 525 sets 5.25% on both buys and sells. Blank websites use the reserved Uplift launch page. Optional image accepts a PNG, JPEG, or WebP data URI up to 128 KiB of text. Resize images in the integrating client. Remote image fetching is not supported.

Reuse the same Idempotency-Key and settings when retrying a reservation. A successful first reservation returns 201; a replay returns 200 with Idempotency-Replayed: true. Changed settings with the same key return 409. The key remains bound to the original reservation.

Every launch endpoint requires Authorization: Bearer <accessToken>. In live mode, reserve with simulate: false. Live preparation and confirmation remain disabled until chain integration is activated. Optional first buys are not part of API creation; firstBuy must be omitted or "0".

Limits and errors

Limits are shared across app instances. One IPv4 address or IPv6 /64 gets 60 requests per minute, with a burst limit of 10 per 10 seconds. POST requests also have a limit of 10 per minute and 4 per 10 seconds. Users behind the same terminal backend or NAT share that budget.

Launch reservations are limited to 5 per hour and 3 pending reservations per wallet. Initial service capacity is 30 API reservations per hour and 300 pending reservations overall. Retries with an existing idempotency key do not consume another reservation.

The small initial deployment also caps total API traffic at 600 requests per minute, with 100 per 10 seconds, and writes at 60 per minute, with 20 per 10 seconds. Capacity can be raised as usage grows. JSON requests are capped at 160 KiB and responses at 256 KiB. Read queries have time limits and use indexed data without making RPC calls.

Use X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset to track the applicable request budget. Reset is a Unix timestamp in seconds. 429 means a client or wallet limit was reached; 503 can indicate a shared capacity limit or temporary unavailability. Honor Retry-After, then use exponential backoff with jitter. Do not retry invalid input or signature failures unchanged.

Errors use {"error":{"code":"...","message":"...","requestId":"..."}}. Retain the request ID when reporting a problem.

Data and versioning

Public data is cached on the server for up to 15 seconds. Use ETag and If-None-Match to avoid transferring unchanged responses. A 304 or HEAD request still counts toward the request limit. Poll active tokens every 15 to 30 seconds, cache token settings, and slow polling for inactive tokens.

meta.generatedAt is the response-generation time, not chain freshness. Use freshness.indexedAt, indexedBlock, and the current, stale, unindexed, or simulated status. A checkpoint more than two minutes old is stale. Missing timestamps and transaction hashes stay null rather than being invented.

A token retains its mechanism ID and rules hash. Unknown future policies return rulesKnown: false and null rules or fee-sharing details. Do not assume that every token uses today’s payout model. New optional response fields may be added to v1; breaking changes will use a new API version. Unsupported query parameters are rejected.

The API is an initial best-effort integration surface, with no uptime SLA. Shared database limits and bounded work protect the application at its current size; they are not a substitute for edge-level traffic protection against a distributed attack.