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.

Top Blast is the display name for the loss-rebate/v1 reward mode. Use the stable mechanism.id and rulesHash when integrating; a display-name change does not change the payout rules. Launch requests use token.mode, which defaults to loss-rebate/v1. Upcoming modes cannot be launched yet.

Creator tax adds to PONS’ standard trading fee, currently 1%. A 500 bps creator tax means 6% combined for non-stock pairs, or 7% for stock pairs after their additional 100 bps stock-pair fee. stockPairTradingFeeBps is 100 for a catalog-verified stock pair, 0 for a non-stock pair, and null if the pair type is unknown. This depends on the pairing asset, not the payout asset. ponsStandardTradingFee distinguishes the default from a verified token rate; combinedTradingFeeBps is null until that rate and the pair’s stock-fee classification are known.

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.

Live payouts

GET /tokens/{token}/payouts/stream sends payout updates using server-sent events. No account or key is required. Token addresses and launch IDs are supported.

const feed = new EventSource(
  "https://uplift.cash/api/v1/tokens/0x.../payouts/stream"
);
feed.addEventListener("snapshot", event => {
  const snapshot = JSON.parse(event.data);
  // Replace totals, round progress and recent payments together.
  renderPayouts(snapshot);
});
// Close the connection when the view is no longer needed.
// feed.close();

A snapshot replaces the previous state and contains exact payout amounts, round progress, recent rounds, the latest 12 payments with transaction evidence, and indexing freshness. It also includes the top paid wallets, fee-sweep schedule, and a bounded market snapshot with holder count, rolling 24-hour volume, price history, and USD display values. The event ID is a content version. It is not a replay cursor. Reconnecting returns the latest complete snapshot, including corrected records. Use the paginated payment endpoint for history beyond the recent window.

checked reports a successful unchanged check. heartbeat keeps the connection open. feed-error reports delayed data or a terminal unavailable token. reconnect asks the client to renew the connection. Preserve the last records and show a delayed state if updates stop; do not animate invented payments.

Active delivery is checked about every 4 seconds; idle tokens about every 15 seconds. These are database checks shared by all viewers on a server, with no additional RPC calls. Chain inclusion and indexing add latency. Streams pause with hidden tabs in the Uplift UI and reconnect automatically.

Market volume counts each swap from the token's verified PONS curve or pool, including routed transactions and multiple swaps in one transaction. Recognizing a market trade does not establish a holder's eligible purchase cost. USD volume uses the current quote-asset conversion rate and can differ from terminals that price each historical trade separately.

Opening a stream uses the standard read limits. Each server supports up to 512 connections, 8 per client network, and 128 watched tokens, with two concurrent snapshot readers. Connections renew after about five minutes. Back off on 429 or 503 responses. Slow consumers are disconnected and should reconnect for a current snapshot.

Wallet lookup

Address-only portfolios use GET /wallets/{wallet}/positions, with up to six positions per page. Remaining purchase lots and source evidence are available at GET /tokens/{token}/wallets/{wallet}/evidence, with up to 12 lots per page. Both support limit and cursor, and use the same public rate limits.

GET /tokens/{token}/treasury-history returns available, reserved and total holder funds, with up to 400 indexed events. Funding reserves funds; delivery removes them. History is withheld while recorded transactions and the index snapshot disagree. USD values use the current conversion rate. These endpoints read indexed data and make no RPC calls.

Use GET /tokens/{token}/wallets/{wallet}?limit=5 with a full 0x address. Reads require no signature, authorization, account, or API key. Mixed-case addresses must have a valid checksum. Token addresses and launch IDs both work.

data.eligibility reports the current indexed check and qualifying shortfall. A null eligible or shortfall means the check is unavailable, not that the wallet has no loss. Statuses explain unrecognized entries, the holding period, outgoing-token disqualification, confirmation, verification, and incomplete pricing. eligibility.unrecognizedSource explains holdings without a verified purchase from their entry blocks’ indexed transfers: outside_pool (filled by a Uniswap v3 pool of the token or a v4 pool other than the launch’s PONS pool), split (partly filled outside PONS), transfer, or unknown, with the pools involved and swapUrl, the Uplift swap that only trades on the PONS curve or pool. Evidence entries carry the same source per lot. This explains a verdict; it never recognizes an entry.

Live checks use a recent confirmed snapshot, chain and accounting verification, and the higher of indexed spot price and the 15-minute time-weighted price. Price volatility alone does not suspend payouts. Newer buys cannot enlarge the snapshot position. Previous funded awards reduce the shortfall even before delivery. Preview tokens use the current preview sweep rules and simulated reserve price.

Holders must hold for at least 15 minutes before qualifying. Payouts use checked provider history with a short confirmation buffer. Ethereum finality is audited in the background and does not set the payout timer. Confirmed history can still reorganize; detected inconsistencies pause new payouts.

data.nextRound provides an estimated award, total eligible shortfall, eligible wallet count and estimated pool. It is null while a round is pending or the checked snapshot is unavailable. Estimates use integer atomic units, round down, and are not promised payouts. position.recognizedValue excludes unrecognized transfers, and position.recoveryComparable is false after outgoing tokens. Completed payments, not funded awards, belong in a received-recovery visual.

GET /tokens/{token}/recovery returns current recovery cohorts and a token-wide next-round estimate. GET /tokens/{token}/rounds/{round}/timeline returns recorded event times and evidence links. Missing times are null. Shareable round receipts are at /receipt/{token}/{round}, with PNG images at /image.png beneath that route.

data.payouts contains complete lifetime totals even when history is paginated. data.history includes funded and paid awards, newest round first. Pass pagination.nextCursor back to this endpoint to retrieve older records for the same wallet. A cursor cannot be reused for another wallet or environment.

Checks read the database only and inherit the API's rate limits, 15-second cache, ETags and page-size limits. checkedAt, freshness and the snapshot fields describe the data used. The qualifying shortfall is not a predicted payout: final eligibility and the proportional award are determined when a round is funded. This endpoint cannot claim rewards or authorize a transaction.

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 have no per-wallet or service-wide count quota, including pending drafts. HTTP traffic and work-capacity limits still apply. Retries with an existing idempotency key return the same reservation.

The small initial deployment also caps total API traffic at 6000 requests per minute, with 1000 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.