Private Beta
API Quickstart

Code blocks are selectable. Copy buttons use your clipboard only; they do not run requests or payments.

Five-minute orientation: overview, request, payment flow and response. Reference tables follow. Contract: schemaVersion: 1.0.0, productVersion: fast-beta-1. Reviewed against repository code on 20 September 2026.

1. Overview

Nex Alpha FAST returns machine-readable pre-trade risk evidence for Base tokens.

FAST provides safety/risk evidence and market/liquidity context, with source provenance, freshness, conflicts and reasonCodes where available. It does not provide an executable quote, route validation, wallet readiness, a BUY signal or financial advice. Your agent remains responsible for its trading and execution decisions.

Private-beta access and paid activation are separate. Production payment activation is gated by provider/commercial rights, an approved mainnet facilitator/configuration, and operational review. A configuration flag is not a provider licence. This guide does not announce live commercial availability.

2. Endpoint and request

POST /v1/fast

The existing configured staging resource is https://nex-alpha-staging-api.onrender.com/v1/fast. It is staging only; its current live availability is not asserted here. Obtain access and the approved resource/payment policy from the beta operator before calling it. Infrastructure-only mode returns 503 STAGING_INFRA_ONLY, not a payment challenge.

https://api.getnexalpha.ai/v1/fast is a planned/custom domain placeholder, not a live production endpoint.

Example request body (Base WETH is an example token, not a recommendation):

{
  "chainId": 8453,
  "token": "0x4200000000000000000000000000000000000006",
  "side": "BUY",
  "amountUsd": "100.00"
}

The body limit is 4 KiB. Unknown body fields and query parameters are rejected. amountUsd is pre-fee notional, not a total-spend cap, token quantity or quote.

Unsigned request template: replace the endpoint and key with the operator-approved resource and your own persisted request key. The example key must not be reused for unrelated requests. This request has no payment proof and does not sign or settle a payment.

curl --include --request POST \
  'https://nex-alpha-staging-api.onrender.com/v1/fast' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: quickstart_example_0001' \
  --data '{"chainId":8453,"token":"0x4200000000000000000000000000000000000006","side":"BUY","amountUsd":"100.00"}'

Use a server-side integration for this quickstart; browser cross-origin API access is not promised. The repository's beta-client-example.js helper returns the challenge without signing or automatically paying.

3. x402 payment flow

Current intended FAST price: 0.05 USDC, or 50000 base units at six decimals. The wire billing.price value is the string $0.05. Token analysis is on Base mainnet (8453); Base Sepolia payment (eip155:84532) is staging only.

1. Send the unsigned POST with your JSON body and persisted Idempotency-Key.
2. When the beta is enabled and ready, receive HTTP 402 and the PAYMENT-REQUIRED header: base64-encoded x402 v2 JSON requirements.
3. Decode and validate against your independently approved policy: x402 version, exact resource URL, network, scheme (exact), asset, amount and payTo. Do not trust a challenge alone to choose the recipient. The current staging client expects one accepted offer, eip155:84532, USDC asset 0x036cbd53842c5426634e7929541ec2318f3dcf7e, amount 50000, and the operator-approved payTo. It also validates timeout and USDC authorization metadata. It is not a mainnet client.
4. Only with explicit payment authorization, sign the payment authorization in your client/wallet. Persist the intent and signed proof securely before submission. No private key belongs on the Nex Alpha server; never send keys or seed phrases in a request, email, or log.
5. Resend the same body, same Idempotency-Key and the signed proof in PAYMENT-SIGNATURE. Reuse the exact original proof on subsequent attempts.
6. The server verifies payment authorization, reserves the request, and gathers evidence. A complete evidence bundle is prepared before settlement. A successful, confirmed settlement returns HTTP 200, the report, billing.state SETTLED, and an initial PAYMENT-RESPONSE receipt header. An incomplete bundle returns 503 with billing.state NOT_SETTLED; a complete bundle may contain blockers or conflicts and still be billable.

Verification is not settlement. A timeout or disconnect after submission does not prove that no payment occurred. The example above intentionally stops at the challenge; it does not contain an automatic payment loop.

4. Read the response

Illustrative excerpt, not a complete wire response or a live token assessment. Only supported fields are shown; other fields and evidence entries are omitted. This shows a complete synthetic bundle with unknown source observation time and confirmed staging settlement. Neither COMPLETE nor SETTLED means safe or executable.

{
  "schemaVersion": "1.0.0",
  "productVersion": "fast-beta-1",
  "mode": "FAST",
  "analysisStatus": "COMPLETE",
  "safety": { "assessment": "UNKNOWN", "blockers": [] },
  "execution": {
    "assessment": "NOT_ASSESSED",
    "priceImpact": "UNKNOWN",
    "accountReadiness": "NOT_ASSESSED"
  },
  "quote": null,
  "reasonCodes": [],
  "conflicts": [],
  "observations": [
    { "source": "contract", "check": "exists", "value": true,
      "status": "OBSERVED", "kind": "RPC_OBSERVATION" }
  ],
  "evidence": [
    { "source": "contract", "status": "OK", "chainId": 8453,
      "fetchedAt": "2026-09-20T12:00:00.000Z", "observedAt": null,
      "fetchAgeMs": 100, "ageMs": null,
      "freshness": "SOURCE_AGE_UNKNOWN", "blockNumber": "123",
      "pair": null, "usable": true }
  ],
  "billing": {
    "state": "SETTLED", "price": "$0.05", "currency": "USDC",
    "network": "eip155:84532", "replayed": false
  }
}

The full report also includes policyVersion, reportId, requestId, input, market, criticalChecks, limitations, timestamp and latencyMs. market can contain pair, counterToken, tokenSide, liquidityUsd and priceUsd; absent/invalid values remain null. Liquidity is not route validation. reasonCodes are machine-readable evidence/limitation codes, such as BUNDLE_INCOMPLETE or HONEYPOT_REPORTED; do not turn unknown codes into a favourable default.

Provenance/freshness is in evidence, not a top-level provenance or freshness object. Local fetch-age limits are 30 seconds for market and 60 seconds for other sources. A known observedAt must also be within the corresponding limit. SOURCE_AGE_UNKNOWN means the fetch time is known but source observation age is not; FRESH is not proof of on-chain block freshness. STALE_OR_INVALID evidence is not usable. Evaluate original timestamps again before acting on a replayed report.

5. Statuses and semantics

CAUTION and BLOCK are not public FAST safety.assessment values. Internal policy BLOCK maps to BLOCKER_OBSERVED and execution BLOCKED. The landing page's simplified API concept is not the FAST integration schema.

criticalChecks.complete is separate from analysisStatus COMPLETE. Individual checks are OBSERVED or UNKNOWN. Conflicts remain explicit and can leave sellability/tax checks UNKNOWN even in a billable complete bundle. FAST provides no riskScore, confidence score or BUY/PASS decision.

6. Redelivery and idempotency

Keep the same Idempotency-Key, body and original payment proof for the same logical request. Retries must not generate a new payment intent, nonce or signature. The key alone does not authenticate retrieval; protect the original proof like a bearer credential and never log it.

After a lost response, repeat the original POST with the same body/key/proof, or retrieve a known reportId:

GET /v1/reports/{reportId}
PAYMENT-SIGNATURE: <original base64 payment proof>

Successful redelivery returns the stored report with billing.replayed true, without another analysis or settlement. The replay does not refresh evidence and need not include the initial PAYMENT-RESPONSE header. reportId/requestId in the report stay stable; X-Request-ID identifies the current HTTP attempt.

If payment is ambiguous (timeout, disconnect, 202 PENDING or 502), never automatically re-sign. Preserve the original intent/proof, use bounded redelivery attempts, and contact the operator for reconciliation. A 409 conflict is not a reason to rotate the key and pay again. Reports are subject to retention and can return 410; retrieval is not indefinite.

7. Errors and pending results

Normal beta error envelopes contain error.code and error.retryable, plus schemaVersion and requestId. retryable is true for 429/503, but this never authorizes another signature or payment intent. Incomplete-bundle 503 replies contain a report and billing instead; infra-only replies use their own mode/error envelope.

8. FAST limitations and contact

• No guaranteed token safety, execution or profitability. Technical intelligence, not financial advice.
• Evidence may be incomplete, conflicting or stale; observed blockers remain visible. Provider claims are not guarantees.
• Base-first/private-beta scope: Base token analysis only, FAST only. No executable quote, route validation, wallet readiness, roundtrip or trading-alpha assessment.
• side, amountUsd and optional taker are context, not proof of an executable order. quote is null.
• The beta/API may change or be discontinued. Use the versioned schema and your own decision policy.

Request access or ask integration questions: sjoerd@getnexalpha.ai. Product: getnexalpha.ai.

Contract references

This guide follows beta-fast.js (input/project), beta-server.js (routes, billing and errors), beta-payment.js and beta-config.js (x402), staging-payment-client.js (challenge validation and retained intent), staging-config.js (activation gates) and staging-infra.js (infra-only replies). PRIVATE_BETA.md provides further context; current code takes precedence over historical sprint notes. No live provider request, signing or payment is needed to read or copy this guide.