NEX ALPHA / DEVELOPER DOCS

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 23 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):

JSON / EXAMPLE 1
{
  "chainId": 8453,
  "token": "0x4200000000000000000000000000000000000006",
  "side": "BUY",
  "amountUsd": "100.00"
}
FieldRequiredCurrent support
chainIdYesJSON number 8453 (Base mainnet analysis), even when payment uses staging.
tokenYesValid EVM token address (strict address/checksum validation); normalized to lowercase.
sideYesExactly BUY or SELL. Request context, not a recommendation.
amountUsdYesDecimal string from 10 to 10000, at most two decimal places; normalized to two decimals. No exponent notation or JSON number.
takerNoValid public EVM address (strict address/checksum validation); context only, no wallet-state assessment.

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.

HeaderWhen / meaning
Content-Type: application/jsonRequired for the JSON POST body.
X-Nex-Beta-KeyRequired on every POST, including unsigned challenges and paid retries. Unique active private-beta credential; never log it or place it in URLs.
Idempotency-KeyRequired on POST, including the unsigned request: 16–80 ASCII letters, digits, underscores or hyphens. Generate once per logical request and persist it.
PAYMENT-SIGNATUREOnly on the authorized paid POST or report retrieval: the original base64-encoded x402 v2 JSON payment payload.

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.

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

The header-file path is a placeholder for an owner-only local file containing the operator-issued X-Nex-Beta-Key header. Keep it outside Git/cloud sync, command arguments and logs. Both client helpers require betaKey in memory. The generic helper destination must come from independently trusted operator configuration, never a challenge or untrusted link; redirects are refused.

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.

JSON / EXAMPLE 3
{
  "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.

fetchedAt records when Nex Alpha started fetching from a source, not when that source updated its underlying data. fetchAgeMs is the local fetch age at report generation; observedAt and ageMs describe the source observation time and age when known. A recent fetch does not establish recent underlying data.

Match each observation's source to evidence[].source. usable=true means the source passed the report's status (OK), chain and timing checks; it does not establish known source age or complete critical checks. A missing or null observedAt can produce SOURCE_AGE_UNKNOWN with usable=true. A supplied unparseable, future or stale observation time produces STALE_OR_INVALID with usable=false. Inspect source status, freshness, observedAt and criticalChecks together: missing or failed sources remain explicit, and a retained observation value may be PARTIAL even when its source is unusable. Recalculate ages from the original timestamps before reuse. COMPLETE is an evidence-bundle status, not a safety approval.

5. Statuses and semantics

ValueMeaning in this implementation
COMPLETEanalysisStatus: usable contract and liquidity evidence plus a usable honeypot/GoPlus security source meet the bundle criteria. Not a safety, execution or trading verdict.
PARTIALanalysisStatus: some usable evidence or a blocker exists but the bundle is incomplete. Also an observation/source status in its own context. Incomplete bundles are not settled.
UNAVAILABLEanalysisStatus: no usable evidence and no retained blocker. Not settled.
UNKNOWNCurrent safety assessment without a retained blocker; also missing/unresolved check evidence and price impact. Never means safe.
BLOCKER_OBSERVEDPublic safety assessment when a security blocker is retained, even if other evidence is missing.
BLOCKED / NOT_ASSESSEDexecution.assessment: blocked by a retained security blocker, otherwise not assessed. accountReadiness remains NOT_ASSESSED.
OBSERVEDA check/observation has evidence; it does not mean a favourable value or confidence score.
SETTLED / NOT_SETTLEDbilling.state on successful paid reports / incomplete-bundle responses respectively. Payment state is separate from safety.
UNCERTAINInternal persisted settlement state requiring reconciliation. Public replies use 202 PENDING with SETTLEMENT_RECONCILIATION_REQUIRED, or 502 SETTLEMENT_UNCONFIRMED; do not expect billing.state UNCERTAIN in a successful report.

CAUTION and BLOCK are not public FAST safety.assessment values. Internal policy BLOCK maps to BLOCKER_OBSERVED and execution BLOCKED. The landing page shows a fictional excerpt using the current FAST report structure and links to a full synthetic analysis report. Neither example is a live API result; the landing example includes no billing or settlement.

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:

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

Revocation blocks subsequent FAST POSTs, including POST replay. Already paid reports remain available through GET /v1/reports/{reportId} with the original PAYMENT-SIGNATURE, without a beta key, subject to report retention and the existing service gates. In-flight work is not cancelled by revocation. A faulty access registry or exhausted analysis quota may make admission false without disabling proof-authenticated report GET or reconciliation. GET has separate rate and capacity limits. Authenticated FAST requests, including challenges and POST replays, consume request allowance; failed analyses do not automatically refund daily reservations. Key rotation does not reset the budget. The live /ready endpoint separates service ready (HTTP 200/503) from new admission; 200 with admission=false can still serve existing reports. If the report ID was lost, contact support without sending a key or 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.

HTTPActual code / categoryClient action
202PENDING; SETTLEMENT_RECONCILIATION_REQUIREDPreserve original proof; reconcile/redeliver, never re-sign automatically.
400INVALID_INPUT, INVALID_URL_ENCODING, INVALID_PAYMENT, PAYMENT_REQUIREMENTS_MISMATCHCorrect validation/policy errors; do not blindly retry payments.
401BETA_ACCESS_DENIEDMissing, unknown and revoked keys receive the same refusal before payment processing. Contact the operator; never re-sign to resolve access.
401 / 404REPORT_AUTH_REQUIRED / REPORT_NOT_FOUND; NOT_FOUNDCheck original proof and report route; reportId alone is insufficient.
402PAYMENT_REQUIRED or PAYMENT_INVALIDValidate the challenge; payment requires explicit client authorization.
405METHOD_NOT_ALLOWEDFAST accepts POST; report retrieval accepts GET.
409IDEMPOTENCY_CONFLICT, REQUEST_IN_FLIGHT, REQUEST_FAILEDPreserve identity; resolve conflict/in-flight/failed state before further action.
410REPORT_EXPIREDStored report is no longer available for normal retrieval.
413 / 415BODY_TOO_LARGE / INVALID_REQUESTRespect body limit and supported JSON encoding.
429RATE_LIMITED, TESTER_RATE_LIMITED, TESTER_DAILY_QUOTA_EXCEEDED, GLOBAL_DAILY_BUDGET_EXCEEDED, FACILITATOR_RATE_LIMITED, FACILITATOR_DAILY_BUDGET_EXCEEDED, REPORT_RATE_LIMITEDHonour Retry-After; preserve original identity/proof. A challenge does not reserve analysis capacity. Never re-sign or rotate a key to bypass limits.
502SETTLEMENT_UNCONFIRMEDAmbiguous payment; reconcile without a new signature.
503ACCESS_UNAVAILABLE, QUOTA_UNAVAILABLE, QUOTA_REVIEW_REQUIRED, STAGING_INFRA_ONLY, NOT_READY, STORE_UNAVAILABLE, CAPACITY_REACHED, REPORT_CAPACITY_REACHED, REQUEST_UNAVAILABLE; or incomplete report with NOT_SETTLEDCheck beta availability and response shape; bounded retry/redelivery only.
500INVALID_REQUEST (fallback internal error)Preserve request context; contact support if persistent.

8. FAST limitations and contact

Nex Alpha is a product/service of Nex Alpha Technologies.

Business contact: Nex Alpha Technologies. 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.