Build on a clear foundation.

Everything you need to understand a launch, follow your funds and integrate with nearlaunch.fun.

From the first quote to the final receipt.

nearlaunch.fun is a custom-pair token launch protocol on NEAR. Each token starts on a constant-product bonding curve with one chosen quote asset. Buyers and sellers trade against virtual reserves; real quote reserves fund same-pair graduation. Every launch carries its own immutable economic policy.

Choose your path

Read state before making assumptions

A catalog asset is not necessarily an enabled trading pair. A connected wallet can hold funds on a different network from the displayed market. A quote can be readable while execution is disabled. Use capability responses and the launch policy together; a successful HTTP request is not trading permission.

These guides distinguish implemented behavior, configured services and planned features. Addresses, fees and curve parameters used for illustration are labelled. The entire guide remains readable when the API is offline.

Read-only quickstart

Make your first requests without a key or wallet signature.

Prerequisites

Run the configured local preview and use its actual origin, normally http://127.0.0.1:5180 in this workspace. The generic API server defaults to port 5173. This guide does not announce a public API hostname or production contract address.

The example runs from the application’s browser console or module context. It only performs GET requests. A missing deployment or RPC failure produces an error, not a fabricated market.

async function get(path) {
  const response = await fetch(path, {
    credentials: 'same-origin', cache: 'no-store',
    signal: AbortSignal.timeout(10000)
  });
  const body = await response.json();
  if (!response.ok) throw new Error(body.error ?? body.status ?? ('HTTP_' + response.status));
  return body;
}
const config = await get('/api/config');
console.log({ configured: config.configured, network: config.network_id,
  launchpad: config.launchpad_id, execution: config.execution });
if (!config.configured) throw new Error('DEPLOYMENT_NOT_CONFIGURED');
console.log(await get('/api/pairs'));

Read a known launch

Use a launch ID from your deployment. ID 0 is an example and might not exist. Preserve source and policy identity; never locate a transaction receiver by symbol alone.

GET /api/launch?launch_id=0
GET /api/fees?launch_id=0
GET /api/transaction-anchor

Health versus readiness

/api/health reports service health; /api/ready evaluates configured dependencies and returns 503 when not ready. Even a 200 readiness result explicitly does not constitute release approval. A preview can serve documentation and assets while execution remains disabled.

Next steps

For a quote, read Trading API. For signed Intents commands, establish an owner session first. No preparation example needs a private key. Public capacity, SLA and version compatibility are not implied by a successful local request.

Connect a wallet

Connection, login and permission to spend are separate steps.

Choose the account

The wallet menu exposes configured NEAR and EVM choices. Extension availability depends on the browser and network. An embedded browser may not expose MetaMask or another extension; use the wallet-supported browser if no provider appears.

Connection is not login

Connection supplies an address and chain. The EVM login challenge establishes a site session and binds origin, account, chain, nonce and expiry. It authorizes profile/community access, not token spending. A trade requires a distinct economic signature.

Network and balance separation

Ethereum ETH, native NEAR, wallet wNEAR and internal Intents wNEAR are separate balances. Mainnet funds cannot trade against local sandbox markets. Native NEAR pays NEAR storage and gas; a wNEAR balance alone does not prove gas availability.

Disconnect and change accounts

Use the wallet menu to disconnect or sign out. This removes the active connection/session but does not revoke a previously signed, still-valid spending payload. Pending jobs remain tied to the original owner. Account changes must invalidate displayed quotes and reload balances, profile identity and account-scoped preferences.

The NEAR connection and EVM session are independent. Logging out of one is not revocation of the other. Never share a seed phrase or private key with support or a documentation example.

Signing scope

The implemented EVM proofs support externally owned accounts. A contract wallet, multisig, passkey account or generic WalletConnect QR connection is not automatically supported just because it has an EVM address. Each needs its own acceptance tests.

Continue with Your Intents account or Deposit funds.

Your Intents account

One owner, internal token balances and a separate trading vault.

Intents balances are recorded inside the verifier under your EVM owner identity. They are not the ETH balance shown by MetaMask and do not have a standalone raw deposit address. The application authenticates the EVM account before reading its private application data.

Connect ownership

1. Connect

   Select the EVM account that will own the funds.

2. Log in

   Sign the site challenge. The server verifies it and creates an HttpOnly session; no transfer is authorized.

3. Read balances

   Check expected verifier, token IDs and network. A failed read stays unavailable rather than becoming zero.

4. Prepare the vault

   For enrolled accounts, create the deterministic keyless NEAR vault and prepare storage. This is the account the curve identifies as trader/creator.

Two places for funds

Intents balance is spendable through an appropriate signed Intents command. Vault balance may contain funding, output or funds awaiting return. A token-by-token total can combine them, but a vault return is not a sale or realized profit.

The vault derives from the lowercase EVM owner and factory. Finalized code, account configuration and keyless status are verified before use. A derived address alone does not prove that the vault has been deployed.

After logout or restart

Ownership persists on chain. Log in again with the same wallet to recover its jobs and profile. EVM sessions currently expire on server restart; the financial journal, signatures and owner locks persist. Do not create a replacement wallet simply because a session expired.

Deposit funds

Review the dollar budget, provider quote and source transfer separately.

Select source and destination

The configured sources include ETH or canonical USDC on Ethereum, Base and Arbitrum. Actual availability is checked against the provider catalog. Select the intended receiving mode: a prepared NEAR account or the Intents account controlled by your EVM wallet. Never send directly to a displayed Intents owner identifier.

Enter dollars

Amount (USD) is a dollar budget: 10 means ten dollars, not ten ETH. At quote time the app converts it into source-token atoms using the checked price observation. Review You send: that token quantity is the actual transfer amount. Its USD value can move before confirmation.

1. Estimate

   Choose source chain/token, destination, budget and slippage. Check route availability.

2. Executable quote

   Where enabled, inspect the concrete route, receiving owner, source amount, minimum output, expiry, refund address and fees.

3. Approve

   Use the correct source chain and inspect destination and amount in the wallet. Origin gas is extra.

4. Track

   Keep the operation ID and hash. Recover a lost response without making another deposit.

5. Verify delivery

   Provider completion and destination receipt/balance proof are separate evidence. A timeout proves neither receipt nor refund.

Fee interpretation

Provider receive amounts already include their own quoted economics. Do not subtract displayed fees again. Possible refund costs and provider metadata are separate from the signed minimum output. A failed route may incur refund fees.

Funding is not buying

External deposit and launch-token purchase are separate stages. Funding does not enable sandbox trading or allowlist a catalog asset. The already-funded curve route does not require experimental customRecipientMsg or a batched ANY_INPUT funding flow. See Intents trading.

Swap and withdraw

Move an existing Intents balance using a distinct reviewed authority.

Selling a launch token, swapping an asset and withdrawing to an external network are separate operations. A curve sale first returns its fixed quote asset to Intents. A later supported withdrawal moves that asset to the chosen destination.

Prerequisites

The signed-operation provider must be configured and its execution enabled. The EVM owner must be authenticated with enough verified input balance. A visible Withdraw control cannot override provider-access or release gates.

1. Choose destination

   Select the supported network, asset and receiving account. Confirm the wallet accepts that token on that network.

2. Review quote

   Inspect source quantity, destination, minimum receive, expiry and fees. USD value is an estimate.

3. Sign

   Approve only the bounded operation whose owner, verifier, nonce, route and limits have been checked.

4. Track the same job

   Keep its ID and exact authority after a lost response. A second quote is not recovery.

5. Verify receipt

   Keep unresolved until destination delivery or a refund is proven. Provider status alone is not independent finality evidence.

Disabled buttons

Check /api/intents-operations/config. INTENTS_PARTNER_ACCESS_REQUIRED means provider execution access is missing. INTENTS_EXECUTION_NOT_ENABLED means the configured route is gated. Neither should be fixed by forcing a button enabled.

Protect pending authority

Signed payloads contain spending authority. Keep them out of logs and support screenshots. Logging out does not invalidate a signature that remains valid on chain. See Recovery.

Launch a token

A complete walkthrough from token details to an active, verified launch.

Prerequisites

• A supported wallet and the correct authenticated account.
• An enabled, verified quote pair from the registry.
• Native NEAR for required setup, or an explicitly configured sponsor on the Intents path.
• A token name and symbol, plus any desired artwork and presentation fields.
• No unresolved earlier Intents launch, trade or fee job for this owner.

1. Describe the token

Open Launch a token. Enter the name and ticker, choose artwork and inspect the preview. Names can repeat: the final token contract and launch ID identify the asset. The token uses 24 decimals and starts with one billion tokens. There is no free creator, team or presale allocation.

Presentation fields and on-chain metadata are separate records. A saved local draft does not establish that images or social links were published. Where enabled, authenticated presentation persistence must finish separately. Inspect the resulting token page and metadata before describing the artwork as published. Never place secrets in metadata.

2. Choose the quote asset

Select what buyers will pay with. Check the network, contract and decimals, not just the symbol. The same quote asset remains through graduation. Later registry changes affect future launches, not this launch. Stock catalog entries remain previews unless a supported representation is verified and enabled.

3. Review the economics

4. Prepare and approve

1. NEAR account path

   Review prepares an unsigned create_launch plan. Inspect wallet network, signer, receiver, method, attached deposit and arguments before approving.

2. Intents account path

   The worker prepares the vault and native budget first. A separate signed Intents command binds metadata, pair version, policy hash, owner vault and deadline. The login signature does not authorize creation.

3. Record the operation

   Preserve the job ID and transaction hash. A lost browser response is not a reason to create a second launch. Inspect the original operation first.

5. Verify activation

Creation spans multiple NEAR receipts. A returned ID can still be in Creating state. The token account must finish deployment and initialization before Active. Lost creation callbacks use recovery; failed creation follows its refund path rather than silently deploying another token.

Inspect the final token contract, creator and policy on the token page. A Review estimate is not a chain receipt. Keep the launch ID and contract address; a ticker such as SAME is insufficient to distinguish launches.

Dev buy and fee destination

The initial-buy calculator estimates a separate paid purchase. Create plus buy is not atomic and gives no first-buyer guarantee. The current EVM launch form requires zero dev buy; purchase uses a fresh quote after activation. See Your first buy.

Where the deployment enables creator fee routing, choose a separate recipient before launch. Ownership and creation refunds stay with the creator. GitHub/X payouts are outside the current scope. See Fee destination.

When to retry

An expired unsigned policy needs a new Review. Once signing has started, recover the existing job instead of requesting another nonce. A wallet rejection does not establish that spending authority never existed. Consult the error reference.

Quote assets

The quote asset is what a token trades against. A TOKEN / USDC pair uses that specific USDC contract for its curve reserve and graduation liquidity. V1 gives each token one quote pair.

Identity comes before a ticker

A name or logo is not verification. The network, NEP-141 account and decimal precision identify a quote asset. Only verified, enabled registry entries appear in the actual launch selector. Catalog previews and Intents discovery do not automatically enable an asset.

Your first buy

Dev buy is an optional purchase, not a reserved allocation. You can skip it, enter the amount you want to spend, or calculate a starting budget from a target token amount.

NEAR cross-contract calls complete asynchronously. Combining screens does not make create-and-buy atomic. The initial-buy intent is separate from creation. The current EVM form requires zero dev buy and a fresh purchase after activation.

Trading & Quick buy

Set a USD budget and slippage in Profile → Trading settings, then enable Quick buy. Market rows and cards use the saved preferences directly, without a second nearlaunch.fun confirmation window. Live settings stay in this browser, scoped to the connected account, network, launchpad and code version. Demo settings never enable live trading.

Zero or empty amount turns Quick buy off; it does not substitute a default purchase. A 0% slippage setting allows no output below the quote. Unsaved edits do not change market buttons.

Before a real trade can be sent

A live flow needs the correct network and contract identities, a fresh quote, balance and storage checks, a deadline, and a minimum output that enforces the user’s slippage limit. Wallet approval, submitted, pending and confirmed are distinct states.

A USD budget needs a configured price provider and a fresh conversion into the actual quote asset. Prices older than 15 seconds or with more than 1% confidence uncertainty are rejected. A live click checks balance, storage, quote, min-out and deadline, then asks your wallet to sign. Network and storage costs are additional. USD value can change during signing. Missing setup is handled in the normal Trade panel. The design board never sends an order.

Trade with Intents

The signed path from internal USDC/wNEAR through the curve to final output.

The EVM wallet signs Intents messages; a personal keyless vault interacts with the NEAR curve. The relayer pays configured native execution costs and cannot choose a different vault owner.

Prepare before signing

The vault, journal and FT storage must exist. Register the curve trader and ensure payout infrastructure is funded. The launch must be Active, earlier output settled and input balance sufficient. Setup handles eligible prerequisites before requesting spending authority.

1. Quote

   Specify launch ID, side, exact amount and slippage. Read finalized policy, output ledger and delivery-counter baselines.

2. Authorize

   One ERC-191 payload includes an optional plain ft_withdraw for the shortfall and auth_call to the owner vault. It fixes input/output tokens, amount, min_out, nonce and deadline.

3. Wait for funding

   Authorization and withdrawal receipts can progress separately. A valid command is not proof the input arrived.

4. Trade

   The vault sends the approved input through the existing NEP-141 curve path. Output has its own ledger and delivery lifecycle.

5. Return

   Settle output and return output plus unused input to the same Intents owner.

6. Complete

   A finalized monotonic token counter must reach the recorded target. A signature, hash or successful input transfer alone is not completion.

Selling

A sell uses the launch token as input and the fixed quote asset as output. It cannot spend tokens held in an unrelated wallet or network. After final delivery the quote asset is inside Intents; external withdrawal is a later action.

Limits

Only the immutable owner through the configured verifier authorizes this vault. Unknown resolver results retain the lock. The direct curve route uses neither Privy nor 1Click signed-operation endpoints. Separate external funding/withdrawal can still require partner access. Real verifier bytecode has local acceptance; funded public-wallet acceptance remains outstanding.

Profile & community

Open Profile from the wallet menu to see the account view, created tokens and creator-fee details. Created-token links carry launch, token and deployment identity, so two tokens with the same ticker still open the correct record.

The bonding curve

The curve holds virtual token and quote reserves, called x and y. Their initial product defines K, which stays fixed. A buy adds net quote and releases tokens; a sell returns tokens and removes gross quote before the seller’s fee is deducted.

Move through an example

This illustration uses the reference geometry: 1B initial virtual tokens, 750 virtual quote units and a 3,000 real-quote graduation target. It excludes fees and atom rounding.

How actual amounts are calculated

The contract works in token atoms with wide integer arithmetic. Fees round up, reserve divisions round up and K is never recomputed after a trade. Tiny orders can therefore be rejected when they produce no positive output.

fee       = ceil(gross_quote × fee_bps / 10,000)
net_quote = gross_quote - fee
new_y     = y + accepted_net_quote
new_x     = ceil(K / new_y)
token_out = x - new_x

At the target, only the amount needed to complete the curve is accepted. Excess offered quote is refunded, and the curve fee is charged only on the accepted gross amount. Fees sit outside the real curve reserve.

Trading fees

A curve trade charges a total fee in the quote asset. That fee is split between the creator and the protocol. The creator share is already inside the total fee; it is not charged a second time.

Different costs, different purposes

The V1 launch token has no transfer tax or holder-rewards tax. There is no extra creator-tax slider and no buyback switch. Always inspect the launch’s own policy instead of assuming every launch uses the example above.

Creator earnings

Your profile shows creator earnings per launch and quote asset. Different quote tokens are not combined into an invented cash balance. A token’s name is never used as its payment identity.

If a payment is delayed

An independent receipt journal can recover a lost settlement callback without resending a successful payout. A proven failed atomic transfer restores claimable funds. When the outcome cannot be proven, the attempt remains pending; a timeout alone does not unlock it.

The native fee keeper and the enrolled-owner Intents fee scheduler have local tests. See Automatic fee delivery for the two-stage settlement. It is not a running public payout service. nearlaunch.fun does not currently promise automatic payments, a claim-free experience, or new creator income after graduation. Fees earned on the curve remain owed after graduation.

Automatic fee delivery

From root fee accrual to a proven balance in the owner’s Intents account.

Eligibility and batching

The scheduler scans at most 20 launches per discovery cycle, preserving its cursor. Only enrolled sandbox/testnet owners with the expected immutable creator vault qualify. A positive per-token threshold controls batching. Trade, setup and fee jobs share an atomic owner lock.

1. Prepare

   Verify creator identity, quote token, vault/verifier storage and native sponsorship.

2. Claim

   Use claim_fee_checked with creator role, expected nonce, minimum amount and policy hash. Recover an existing payout before another claim.

3. Separate amounts

   Record initial vault balance, previously paid fees and initial delivery total. Held funds can include unused funding or refunds.

4. Deliver

   Reach the absolute per-token target at the immutable Intents owner. Root paid alone is insufficient.

Return is not all earnings

The root marks paid when the vault received the fee. Final Intents delivery is separate. A return of 25 units can contain 20 units of new fees plus 5 units of unused funding. The API records these components; treating the full 25 as creator earnings would be wrong.

Retries and budget

Signed bytes persist before broadcast. Timeouts reuse the same transaction. Settled partial/rejected deliveries retry the same absolute target, up to three attempts per delivery step. Unknown results stay locked. Fee/setup signatures reserve conservative native sponsorship before signing; a timeout never refills the budget.

Availability

This flow has local real-verifier acceptance including a matching final balance increase. It is not an operated public payout service. Public enrollment, budgets, alerts and funded acceptance remain. No new post-graduation creator revenue mechanism is implied.

Fee destination

Keep token ownership separate from the immutable fee beneficiary.

Choose before launch

On deployments that expose creator_fee_routing, open Fee wallet & launch rules in the pair step. Leave the field empty to receive your own fees, or choose a NEAR account or a full EVM wallet address. Review shows the token creator and the resolved fee recipient separately. The recipient is bound to the immutable policy and creation signature.

NEAR recipient

The account must exist and be registered for the quote token. Payments use that NEAR account; the form does not interpret a raw EVM address as a NEP-141 recipient.

EVM recipient

The address must already have its deterministic, verified Intents vault. The API checks its owner, factory, contract code, journal and token storage. The curve pays this vault. A later authorized delivery moves funds to the same owner inside Intents; it is not an automatic withdrawal to Ethereum, Base or another chain.

Ownership and refunds

The creator remains the launch owner. Creation refunds and trading outputs stay with that owner. Creator fee earnings appear under the beneficiary; creating a token does not entitle you to fees redirected to someone else.

Existing launches and availability

Existing recipients cannot be changed. Older deployments retain their original behavior. Unsupported deployments, missing accounts and incomplete storage fail before signing. The new routing code is undergoing local contract acceptance; public deployment and independent review are separate release requirements. GitHub/X usernames, holder rewards and graduation creator income are not supported by this option.

Graduation & liquidity

Graduation begins when real quote reserves reach the launch’s target. The curve stops trading at that exact threshold. An adapter coordinates the next steps; a completed curve is not by itself a live pool.

1. Close and snapshot.

   Freeze curve trading and calculate the liquidity amounts, residual burn and separate migration fee.

2. Fund the same-pair pool.

   The Rhea / Ref simple-pool adapter registers storage, deposits the planned assets and adds liquidity with the required ratio and minimum amounts.

3. Complete custody and burn.

   The keyless adapter holds LP shares with no withdrawal endpoint. Residual launch tokens are burned. Both steps must succeed before finalization.

4. Finalize once.

   Confirm graduation and credit the one-time migration fee. Outstanding trader deliveries and curve-fee liabilities remain separate.

What the liquidity lock means

The adapter has no LP-transfer, withdrawal, key-addition or upgrade endpoint. That constrains its liquidity custody; it does not eliminate dependencies on the external exchange, quote-token issuer or root deployment authority. Migration can be delayed by failed receipts or hostile pool initialization.

The M6 implementation was exercised locally against pinned Rhea / Ref and USDC bytecode. This is local integration evidence, not a public deployment or an independent audit. V1 does not create a new post-graduation creator-fee stream.

Graduation and market cap

Reserve targets, NEAR/USD and the difference between FDV and collateral.

Graduation is triggered by the fixed net real-quote target, not directly by USD market cap. The final buy is capped to hit the target exactly and returns excess input.

Reference geometry

These are illustrative parameters, not production economics: one billion tokens, 750 initial virtual quote, 3,000 real-quote target and 50 quote migration fee.

NEAR price changes the display

For a wNEAR pair, illustrative prices of $2 and $4 make pre-burn FDV $37,500 and $75,000 respectively. The reserve target remains 3,000 wNEAR. These are not live prices. A fresh USD feed values the launch without rewriting its immutable terms.

Liquidity and burn

lp_quote = real_quote - migration_fee
lp_tokens = floor(lp_quote * final_x / final_y)
burn = final_x - lp_tokens

lp_tokens ≈ 157.333333M
burn      ≈ 42.666667M
supply    ≈ 957.333333M after burn

After burn, FDV changes because supply changed. The reference opening spot price stays near the final curve price up to integer rounding, while reduced-supply FDV is approximately 17,950 quote. Read finalized token supply and pool state before treating a projected burn as complete.

Valuation is not redeemable cash

Spot price values a marginal unit. It is not the price every holder can exit at simultaneously. Fees, reserve movement, liabilities and liquidity affect fills. Keep market cap, net collateral and pool liquidity separate.

After graduation

Pool verification, execution gates and liabilities that remain payable.

Curve closure

ReadyToGraduate ends curve buying and selling. Graduating means adapter work is still in progress, not that the DEX pool is ready. The worker must complete liquidity, LP custody, residual burn and finalization.

Verify the actual venue

Check configured exchange, token pair, pool identity, reserves, fee and custody state. Matching symbols are insufficient. Pool quote calculation is read-only and does not establish a safe executable swap.

Deadline gate

The current direct Rhea path lacks the required user deadline at actual swap execution. Sending is therefore gated. A browser timestamp check before signing cannot replace enforcement after network delay.

Creator liabilities

Previously earned curve fees and trader output remain owed after graduation. Pool trading does not create a new creator fee in this version. That needs a separately implemented venue mechanism.

LP custody

The keyless adapter has no LP withdrawal method, but still depends on exchange behavior, quote issuer restrictions and root deployment authority. Review those dependencies independently from the adapter’s own restrictions.

Developer overview

The boundaries between the browser, API, relayer and contracts.

The application API is the integration surface in this repository. It is not a released public mainnet SDK or an SLA. Use a configured local/testnet instance and inspect capabilities before preparing a workflow.

Four layers

1. Read and review

   The API anchors contract reads to finalized state, checks identities and code, recomputes policy hashes and returns source information with exact integer amounts.

2. Authorize

   The browser verifies the plan and asks the wallet to sign. NEAR signatures, EVM login messages and Intents spending payloads are not interchangeable.

3. Execute

   The worker persists signed transaction bytes and nonce reservations before broadcast. Contracts validate economic authority again.

4. Prove the outcome

   Output ledgers, independent receipt evidence and delivery counters establish completion. A hash or provider status is not equivalent to final delivery.

Versioning

Policy and command domains are versioned independently of this website. The vault code and storage changed when monotonic delivery counters were introduced. Immutable older vaults cannot be upgraded by replacing a frontend bundle. Keep every old job bound to its original factory, verifier, vault and code identities.

Use modules served at the application’s /sdk paths or the repository modules. There is no documented npm install nearlaunch-sdk package. The wallet bundle and server must agree on the exact command schema; see Amounts and schemas.

Authentication and signatures

Session access is separate from economic authority.

EVM login handshake

POST /api/intents/challenge
Content-Type: application/json
{"account":"<lowercase EVM address>","chainId":"0x1"}

# Validate and sign the exact returned site login message.
POST /api/intents/login
Content-Type: application/json
{"signature":"<login signature>"}

GET /api/intents/session
POST /api/intents/logout
Content-Type: application/json
{}

The challenge binds origin, account, chain, nonce, issue time and expiry. A login attempt consumes it even when a signature is invalid. The current challenge lifetime is five minutes; EVM sessions last up to twelve hours and expire on process restart.

Request context

Use the configured HTTPS origin outside loopback development. Origin/Host checks and HttpOnly, SameSite=Strict cookies protect session use; HTTPS cookies are Secure. Use same-origin credentials. A query-string account cannot replace the authenticated owner.

Spending signatures

Login does not authorize create, buy, sell or withdraw. Each spending command binds verifier, owner, domain, network, vault, nonce, deadline and action-specific limits. Persist the signing lock before opening a wallet. Rejection or lost response does not prove a signed payload cannot exist elsewhere.

Native NEAR session

The separate native profile/community path uses NEP-413 and verifies an authorized full-access key against finalized state. Do not mix its session or CSRF data with EVM cookies. A session lets its owner edit app data but is not a blanket on-chain spending allowance.

Limits

The current EVM account handler caps bodies at 4 KiB and challenge/login POST attempts at 12 per minute per client address. Other endpoint families have separate limits. Handle 429 with backoff; do not retry through another identity to bypass controls.

Amounts and snapshots

Avoid decimal loss, wrong assets and mixed-block views.

Integer strings

Token balances, fee amounts and curve inputs/outputs are JSON strings of raw atoms. Keep them as strings and use BigInt or equivalent exact arithmetic. JavaScript Number cannot represent arbitrary u128 amounts. Launch tokens have 24 decimals; quote assets preserve their own verified precision.

1 launch token = "1000000000000000000000000"  // 24 decimals
1 USDC         = "1000000"                    // verified 6-decimal token only
1 wNEAR        = "1000000000000000000000000"  // 24 decimals

// Parse decimal text and scale exactly.
// Do not multiply a floating-point Number by 10 ** decimals.

Basis points

100 bps equals 1%; zero slippage is valid. Fees round up in quote atoms. Creator/protocol split remainders carry forward instead of discarding each fractional share. Use the SDK and contract rules, not a separate floating-point approximation.

Identity

Network and contract identify a token. A market also has its root launchpad and launch ID. Names, symbols, artwork and social URLs are metadata. Tokens sharing SAME as a symbol retain independent balances and fee records.

Source envelopes

Contract responses include network_id, launchpad_id, code_hash, block_hash, block_height and observation/expiry information. Do not combine a quote from one block with a policy from another deployment. Cached data retains its original observation time. A cache hit must not make an old price appear fresh.

Unavailable versus zero

Absent price/history/balance proof requires an unavailable state. Zero means a successful read proved zero. Inspect coverage and pagination before showing lifetime earnings or P&L. A provider’s status or expected code hash is not an independent chain attestation.

HTTP endpoint directory

Implemented routes, methods, account scope and side effects.

Paths are relative to your configured origin. Write routes need their session, origin checks and capability gates. GET views do not sign transactions. POST preparation may create persistent owner locks even before a signature.

Deployment and market reads

Authenticated Intents curve

Funding and provider operations

/api/funding/ provides config, assets, quote-usd, quote, prepare, attempt, record, status and abandonment tracking. /api/intents-operations/ provides config, quote, prepare, sign, submit, status, history and cancel. Each family has its own schema and journal: a curve job ID cannot be used as a funding ID. Their execution capabilities must be checked separately.

Identity and community

/api/intents/ handles challenge, login, logout, session and balance. /api/community/ uses native account authentication for profiles/messages. /api/intents-community/ uses the EVM owner session for profile and message writes. Optional sandbox guest chat is not production identity.

Launch API walkthrough

Bind the reviewed economics before requesting a signature.

Get Review

GET /api/review?pair_id=<enabled-pair-id>&creator=<NEAR-creator-account>

The response includes source, policy/hash, template and readiness data. Creator must match the transaction caller. For Intents this is the personal owner vault, not the EVM address or shared verifier.

Native create_launch arguments

{
  "pair_id": "<enabled pair>",
  "expected_pair_version": "<review version>",
  "expected_policy_hash": "<verified policy hash>",
  "deadline_ms": "<reviewed future deadline>",
  "metadata": {
    "spec": "ft-1.0.0", "name": "Example", "symbol": "EXAMPLE",
    "icon": null, "reference": null, "reference_hash": null, "decimals": 24
  }
}

The current root requires an exact 0.1 NEAR creation deposit and at least 150 Tgas. This deposit funds account/storage creation and a defined remainder/refund ledger; it is not entirely a platform fee. Use current deployment Review and never submit expired or stale-version authority.

Intents creation

POST setup with kind create and pair_id. Once ready, prepare with kind create, pair_id and metadata. The server builds a fresh bound command. Follow the job lifecycle; an EVM signature on an arbitrary NEAR JSON transaction is not this protocol.

Verify activation

A command can return a launch ID while initialization is still Creating. Inspect final state and creator. Lost callbacks use root recovery; CreationFailed needs its defined refund path. Never infer activation from a hash alone.

Presentation and dev buy

On-chain metadata is bounded. App presentation needs separate authenticated persistence where enabled. The first buy uses a new quote after activation; integrations must not advertise atomic priority or a free allocation.

Quotes, buys and sells

Exact inputs, execution guards and output settlement.

Account-specific quote

GET /api/trade-quote?launch_id=0&account=<NEAR-account>&side=buy&amount=<quote-atoms>&slippage_bps=100
GET /api/trade-quote?launch_id=0&account=<NEAR-account>&side=sell&amount=<launch-token-atoms>&slippage_bps=100

A buy amount is gross quote input; a sell amount is launch-token input. Slippage is basis points. The response binds account, launch, policy and source. Execution preparation checks storage and unsettled output as well.

Protect the actual transaction

Use the repository builder to construct the NEP-141 transfer-call with the correct receiver, deposit, gas and bounded trade message. The root checks predecessor token, launch, deadline and min_out. Showing a minimum in the UI is not protection if the signed transaction omits it.

Graduation cap

The final buy may accept less than offered. The contract finds the accepted gross amount that reaches the exact net reserve target. Fees apply to accepted input, and excess returns. Display accepted input, fees, output and refund independently.

Output settlement

Input usage does not prove output receipt. The trader ledger tracks accrued, claimable, in-flight and paid output in base or quote. Claiming an existing output must not rerun the trade. Ambiguous delivery retains its lock for receipt recovery.

Quick buy

Quick buy starts with a saved USD budget and fresh checked conversion, then follows the same quote/signature protections. Zero disables it. It cannot bypass wallet approval, setup or release gates. For EVM users use the Intents route instead of impersonating a NEAR account query parameter.

Intents job lifecycle

Prepare, lock, sign, submit and recover one logical operation.

1. Identity and capability

Authenticate, then read curve config and account. Address returns a derived account with deployed_status not_checked; account verifies the actual vault. All curve routes require the owner session.

2. Complete setup

{"kind":"trade","launch_id":"0"}

202 queues setup. Poll GET setup?id=… until the stored state is ready. A 200 ready response means a fresh check found prerequisites already satisfied. Setup can create vault/journal, register FT storage and trader state, or replenish native budget for enrolled acceptance accounts.

3. Prepare once

{
  "id":"<UUID for this logical operation>",
  "input": {
    "kind":"trade", "launch_id":"0", "side":"buy",
    "amount":"<gross quote atoms>", "slippage_bps":100
  }
}

The response contains id, plan and capability. Persist the ID before wallet interaction. Retries use identical input and the same ID; different input or a competing owner job is rejected. This POST creates durable state, not just a stateless quote.

4. Validate, lock and sign

POST /api/intents-curve/sign
{"id":"<same UUID>"}

# Validate plan.intent and command with the shipped verifier.
# Ask the wallet to sign the exact ERC-191 payload.
POST /api/intents-curve/submit
{"id":"<same UUID>","signature":"<spending signature>"}

GET /api/intents-curve/job?id=<same UUID>

The sign route records a lock before the wallet opens. Submission validates and stores authority before external execution. The worker reserves NEAR nonces and persists signed bytes before sending. Keep signatures, cookies and serialized spending authority out of logs.

5. Completion states

Cancel and expire

Cancel applies only to truly unsigned prepared state. Expiry requires finalized time past deadline, same verifier salt, unused verifier nonce and unchanged idle vault. Consumed nonce requires auth/withdrawal receipt reconciliation; time alone is insufficient.

Return commands

Return input specifies token and amount. The server binds an absolute target from the finalized delivery baseline. Old plans without a baseline require review, not an invented zero. Never reinterpret an old signed job for a new factory or code hash.

Profiles, fees and history

Query the right owner and preserve completeness across pages.

Identity and pagination

Native profiles accept a NEAR account. Intents profiles use the authenticated EVM owner and resolve its vault. Shared-verifier activity cannot be assigned to one EVM user. Creator-recipient checks precede aggregation.

Preserve returned cursors exactly. Profile pages retain their original contract snapshot; app and fee history have separate database cursors and at most 50 rows per page. Never mix cursor domains or merge pages from different snapshots as one complete result.

GET /api/intents-curve/profile?limit=50
GET /api/intents-curve/holdings?cursor=0
GET /api/intents-curve/history
GET /api/intents-curve/fee-history

Coverage labels

Fee accounting

Accrued includes paid amounts; claimable and in-flight are liabilities still being settled. Root paid means payment to the fixed recipient, possibly a vault. Final Intents delivery has separate proof. Group assets by contract and avoid adding different tokens into an unpriced cash total.

P&L and trending

P&L needs complete trade/transfer history and an explicit valuation method; missing basis remains null. Native indexing does not automatically include internal Intents transfers. Trending must disclose its indexed or loaded-market scope rather than imply global coverage.

Contract architecture

Custody, authorization and pinned code identities.

Immutable boundaries

A policy snapshot fixes launch economics. A keyless vault with a global code hash limits its own upgrade path. Those do not remove root deployment authority, an external exchange upgrade, quote-issuer freeze or verifier governance action. Revalidate dependencies before constructing authority.

Per-owner attribution

The curve sees a unique NEAR account per EVM owner. Output, creator identity and fees remain separate across users. The relayer is not an omnibus owner and must not be displayed as the user’s token balance account.

Address publication

Sandbox accounts are ephemeral fixtures, not production addresses. Publish verified mainnet addresses, route configuration, immutable economics and reviewed hashes only through the release process. The expected code hash returned by configuration is not itself a fresh chain attestation.

Configured deployment

The values below are local API configuration, not a verified mainnet address list.

Pending operations and recovery

Follow receipts without replaying a payment.

Asynchronous execution

A NEAR transaction can be accepted while token delivery and callbacks are still running. Browser/RPC timeouts describe the client’s observation, not whether funds moved. Preserve the original ID, owner, network, vault/root, action and hash.

Evidence-based actions

Stable delivery

The vault increments its token credit total only after bounded successful resolver evidence. The worker records baseline and absolute target. A caller who already reached that target makes a repeat transfer unnecessary; partial settled delivery sends only the remainder. This removes reliance on a mutable last-delivery record.

Still-open cases

Consumed nonce with missing/divergent auth or withdrawal evidence, unavailable resolver proof and expired unknown NEAR transactions still require investigation. Do not delete rows, decrement nonces or create replacement authority to make progress appear successful.

Support evidence

Share public hashes, network, account, job ID and redacted error. Do not expose private keys, seeds, cookies, provider keys or raw signed payloads. Preserve the private journal before service restarts. Native transaction recovery also needs its finalized pre-submission anchor; matching only the amount is insufficient.

Error reference

Missing prerequisites, rejected requests and uncertain economic effects.

Keep the exact bounded error code and job ID. A 503 can mean missing configuration or failure to verify state, not merely temporary congestion. Separate read retries from spending operations.

Prices and HTTP codes

Refresh stale prices before a new unsigned order; never rewrite timestamps. An already signed operation is tracked under its original ID. 401 needs login, 403 needs correct context, 415 needs JSON content type, and 429 needs bounded backoff. Use capped read retries with jitter and cancellation. Do not create a new signed spend because a previous HTTP call failed.

Services and configuration

Run independent responsibilities with bounded authority.

Service responsibilities

The API serves verified reads, sessions, profiles and operation preparation. The indexer provides history and coverage watermarks. Fee, graduation and Intents workers progress durable jobs. The checked USD adapter values budgets; it cannot change immutable curve parameters.

Configure before execution

Select network, root/code identity, RPC, HTTPS origin, database paths and services. Intents needs factory, vault hash, verifier, dedicated signer and worker. Mainnet code gates remain closed; a JSON flag is not release approval.

Sponsorship

Setup/fee eligibility uses an explicit owner list, owner lifetime, UTC daily and total limits, maximum storage cost, native target and gas-price ceiling. Conservative reservations persist before signing; refunds and restores do not refill allowances. Continuous trade-worker gas/backoff policy remains a release requirement.

Process discipline

Run one worker per private journal with a dedicated signer. Durable nonce reservation and the process lock prevent concurrent authority use. Earlier signed NEAR transactions must finalize before higher nonces are broadcast. A stuck earlier transaction can therefore affect later-job liveness.

node services/keeper/intents-curve-cli.mjs <deployment.json>
# One bounded cycle:
node services/keeper/intents-curve-cli.mjs <deployment.json> --once

NEARLAUNCH_CURVE_RELAYER_KEY belongs in the server environment, never JSON, browser code, docs or logs. These commands are not permission for a public financial deployment.

Monitor

Track RPC/code mismatch, index lag/coverage, heartbeats, pending age, unresolved settlement, sponsorship reservations, signer gas and backup freshness. Distinguish no work from inability to advance funded work. Readiness is scoped operational evidence, not an independent audit.

Backups and restoration

Preserve signed authority and reconcile chain state before resuming.

What to preserve

The journal contains owner locks, exact signed payloads, serialized NEAR transactions, nonce reservations, setup/fee jobs, sponsor reservations and proofs. A profile-only backup is not sufficient. Protect the archive as sensitive authority.

Consistent snapshots

Use the SQLite snapshot procedure. Copying the main file while its WAL is active can omit committed state. Store database hashes, identity and a separately trusted manifest hash. Protect off-host copies from disclosure and deletion.

1. Verify archive

   Check the trusted manifest, expected database set and file hashes.

2. Verify identity

   Match network, root, code, schema and application origin.

3. Stage separately

   Restoration does not enable execution.

4. Reconcile

   Transactions can finalize after backup. Recheck every pending authority and chain effect before resuming.

5. Resume under supervision

   Preserve locks, fee scan cursor, reservations and exact transaction bytes. Reauthenticate sessions as required.

No resets

Deleting a stuck row can remove the only record of valid spending authority. Recreating a target or decrementing a nonce can duplicate accounting. A backup is evidence for reconciliation, not permission to replay all old work.

Acceptance

Local restoration tests cover pending jobs, locks, bytes, counters and budget reservations. Production still needs off-host recovery, host loss, RPC outage and post-backup finalization exercises. A local restore test does not prove that a VPS backup schedule is running.

Status & trust

Local tests, a working interface and a production deployment are different milestones. This guide describes the implemented V1 mechanics and the current preview boundaries.

The trust assumptions

• Deployment authority. The launchpad root’s deployment authority remains a trust boundary. A policy snapshot does not remove that authority.
• External contracts. An observed exchange code hash does not prevent a later external upgrade. Quote issuers may have pause, freeze or blocklist powers.
• Settlement evidence. If both result observers fail, recovery may remain unresolved. The protocol does not infer success from a timeout or account balance.
• Market execution. Reserve movement, competing transactions and thin liquidity can change execution. Minimum output limits unacceptable fills; it cannot guarantee order priority.

Reference standards: NEAR cross-contract calls ↗, NEP-141 ↗ and NEP-148 metadata ↗.

Release status and acceptance

Implemented code and public availability are distinct milestones.

Prove outcomes

Each public acceptance flow needs approved payloads, transaction hashes, final receipts and expected balance/ledger changes. Redact sensitive authority from shared evidence. Cover buy, sell, partial/refunded buy, creator fee, missing storage, account changes, rejection, provider delay and lost callbacks. A quote response is not a completed purchase.

Measure latency honestly

Separate wallet prompt/approval, submission, inclusion and final token delivery. Measure already-funded USDC/wNEAR and external funding flows independently. Local already-signed timings exclude human approval, public RPC/chain conditions and provider delay. They cannot establish a speed advantage over another app.

Before rollout

Complete exceptional receipt reconciliation, ongoing worker gas/backoff, canonical asset acceptance, external venue checks, operational recovery and independent review. Publish exact deployment identities and immutable economics. Staged limits and explicit acceptance criteria are required; one passing test suite is not blanket approval.

Common questions

Glossary

Terms used in balances, quotes, fees and settlement.