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):
{
"chainId": 8453,
"token": "0x4200000000000000000000000000000000000006",
"side": "BUY",
"amountUsd": "100.00"
}| Field | Required | Current support |
|---|---|---|
| chainId | Yes | JSON number 8453 (Base mainnet analysis), even when payment uses staging. |
| token | Yes | Valid EVM token address (strict address/checksum validation); normalized to lowercase. |
| side | Yes | Exactly BUY or SELL. Request context, not a recommendation. |
| amountUsd | Yes | Decimal string from 10 to 10000, at most two decimal places; normalized to two decimals. No exponent notation or JSON number. |
| taker | No | Valid 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.
| Header | When / meaning |
|---|---|
| Content-Type: application/json | Required for the JSON POST body. |
| X-Nex-Beta-Key | Required on every POST, including unsigned challenges and paid retries. Unique active private-beta credential; never log it or place it in URLs. |
| Idempotency-Key | Required on POST, including the unsigned request: 16–80 ASCII letters, digits, underscores or hyphens. Generate once per logical request and persist it. |
| PAYMENT-SIGNATURE | Only 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.
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.
- Send the unsigned POST with your JSON body and persisted Idempotency-Key.
- When the beta is enabled and ready, receive HTTP
402and thePAYMENT-REQUIREDheader: base64-encoded x402 v2 JSON requirements. - 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 asset0x036cbd53842c5426634e7929541ec2318f3dcf7e, amount50000, and the operator-approved payTo. It also validates timeout and USDC authorization metadata. It is not a mainnet client. - 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.
- Resend the same body, same Idempotency-Key and the signed proof in
PAYMENT-SIGNATURE. Reuse the exact original proof on subsequent attempts. - 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.stateSETTLED, and an initialPAYMENT-RESPONSEreceipt header. An incomplete bundle returns503with billing.stateNOT_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.
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
| Value | Meaning in this implementation |
|---|---|
| COMPLETE | analysisStatus: usable contract and liquidity evidence plus a usable honeypot/GoPlus security source meet the bundle criteria. Not a safety, execution or trading verdict. |
| PARTIAL | analysisStatus: 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. |
| UNAVAILABLE | analysisStatus: no usable evidence and no retained blocker. Not settled. |
| UNKNOWN | Current safety assessment without a retained blocker; also missing/unresolved check evidence and price impact. Never means safe. |
| BLOCKER_OBSERVED | Public safety assessment when a security blocker is retained, even if other evidence is missing. |
| BLOCKED / NOT_ASSESSED | execution.assessment: blocked by a retained security blocker, otherwise not assessed. accountReadiness remains NOT_ASSESSED. |
| OBSERVED | A check/observation has evidence; it does not mean a favourable value or confidence score. |
| SETTLED / NOT_SETTLED | billing.state on successful paid reports / incomplete-bundle responses respectively. Payment state is separate from safety. |
| UNCERTAIN | Internal 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:
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.
| HTTP | Actual code / category | Client action |
|---|---|---|
| 202 | PENDING; SETTLEMENT_RECONCILIATION_REQUIRED | Preserve original proof; reconcile/redeliver, never re-sign automatically. |
| 400 | INVALID_INPUT, INVALID_URL_ENCODING, INVALID_PAYMENT, PAYMENT_REQUIREMENTS_MISMATCH | Correct validation/policy errors; do not blindly retry payments. |
| 401 | BETA_ACCESS_DENIED | Missing, unknown and revoked keys receive the same refusal before payment processing. Contact the operator; never re-sign to resolve access. |
| 401 / 404 | REPORT_AUTH_REQUIRED / REPORT_NOT_FOUND; NOT_FOUND | Check original proof and report route; reportId alone is insufficient. |
| 402 | PAYMENT_REQUIRED or PAYMENT_INVALID | Validate the challenge; payment requires explicit client authorization. |
| 405 | METHOD_NOT_ALLOWED | FAST accepts POST; report retrieval accepts GET. |
| 409 | IDEMPOTENCY_CONFLICT, REQUEST_IN_FLIGHT, REQUEST_FAILED | Preserve identity; resolve conflict/in-flight/failed state before further action. |
| 410 | REPORT_EXPIRED | Stored report is no longer available for normal retrieval. |
| 413 / 415 | BODY_TOO_LARGE / INVALID_REQUEST | Respect body limit and supported JSON encoding. |
| 429 | RATE_LIMITED, TESTER_RATE_LIMITED, TESTER_DAILY_QUOTA_EXCEEDED, GLOBAL_DAILY_BUDGET_EXCEEDED, FACILITATOR_RATE_LIMITED, FACILITATOR_DAILY_BUDGET_EXCEEDED, REPORT_RATE_LIMITED | Honour Retry-After; preserve original identity/proof. A challenge does not reserve analysis capacity. Never re-sign or rotate a key to bypass limits. |
| 502 | SETTLEMENT_UNCONFIRMED | Ambiguous payment; reconcile without a new signature. |
| 503 | ACCESS_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_SETTLED | Check beta availability and response shape; bounded retry/redelivery only. |
| 500 | INVALID_REQUEST (fallback internal error) | Preserve request context; contact support if persistent. |
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.
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.