NeuraMesh local API reference

Base URL and safety boundary#

Start the server with npm run api. The default port is 8787, configurable through NEURAMESH_API_PORT. The Vite development proxy forwards /api calls to that default port. These are local development endpoints, not a documented hosted production API.

The server accepts JSON request bodies but has no hardened field validation, authentication, authorization, rate limits, durable persistence or idempotency support. It binds without an explicit loopback-only host and returns a permissive origin header. Keep it on a trusted development machine and do not expose it to untrusted traffic.

GET /api/health#

This endpoint is the simplest backend connectivity check. The settlement label is a fixture describing the intended stack, not proof that a Sui transaction worker or Walrus connection is active. Always read liveTrading: false as part of the response context.

{"status":"prototype","settlement":"sui-walrus-testnet","liveTrading":false}

GET /api/gpu-prices#

This route fetches a public third-party GPU pricing feed with a ten-second timeout, checks that the payload carries a models array, and republishes it with a source name, the upstream URL and a retrievedAt timestamp. The marketplace page uses it for price context. An upstream failure, timeout or unexpected shape returns HTTP 503 with a short error message rather than stale or invented data.

The retrievedAt value records when the proxy fetched the feed; it is not a provider requote. These are external network-wide figures, not NeuraMesh inventory, a NeuraMesh quote or a guarantee that the listed capacity is purchasable. The same handler is deployed as a serverless function so the hosted marketplace can read the feed without the local server.

{
  "source": "Akash Network",
  "sourceUrl": "https://console-api.akash.network/v1/gpu-prices",
  "retrievedAt": "<ISO timestamp>",
  "models": [ /* upstream records, passed through unchanged */ ]
}

GET /api/stock-history#

Returns daily closing prices for one of five listed companies whose results track AI compute demand: NVDA, AMD, MSFT, AMZN and GOOGL. Accepted ranges are 1mo, 3mo, 6mo and 1y. Symbol and range are both checked against an allow-list, so an unrecognised value returns 400 rather than being forwarded upstream. Responses are cached for fifteen minutes.

The upstream is a public but undocumented endpoint with no stability guarantee or redistribution licence, so treat it as reference context rather than a dependable source. These are equity prices: they describe a company, not the cost of a GPU-hour, and they are not a NeuraMesh market, quote or tradable instrument. Any failure returns 503 and the interface falls back to its own labelled series.

// GET /api/stock-history?symbol=NVDA&range=3mo\n{\n  "symbol": "NVDA",\n  "range": "3mo",\n  "name": "NVIDIA Corporation",\n  "currency": "USD",\n  "source": "Yahoo Finance",\n  "retrievedAt": "<ISO timestamp>",\n  "points": [ { "t": <epoch ms>, "v": <close> } ]\n}

GET /api/markets and GET /api/portfolio#

Markets no longer returns sample contracts. It responds 200 with status unavailable, an empty markets array and a reason string, because the prototype has no verified supply to list. There is no query filtering, individual-market route or reference index endpoint.

Portfolio returns status unavailable with null account, balances and positions. No wallet or account system is connected, so the endpoint cannot report any user holdings or returns.

// GET /api/markets
{
  "status": "unavailable",
  "markets": [],
  "reason": "NeuraMesh Trade has no verified markets yet. Browse external GPU pricing in the Marketplace."
}

// GET /api/portfolio
{
  "status": "unavailable",
  "account": null,
  "balances": null,
  "positions": null,
  "reason": "Account access is not available in this prototype."
}

POST /api/orders, /api/swap/quote and /api/settlements#

All three write routes are refused. The server matches the method and path, then returns HTTP 503 with status unavailable and a single error message. It does not read the request body, validate fields, calculate a quote, allocate collateral, reserve provider capacity or keep a record. Restarting the process changes nothing, because nothing is stored.

Earlier revisions of this scaffold staged caller-supplied objects in process memory and returned 201 or 200. That behavior has been removed, so no local response can be mistaken for an accepted order, a usable swap rate or a settlement record. Treat these routes as placeholders for flows that production must define with validated schemas, authenticated account authority and idempotency keys.

curl -i -X POST http://localhost:8787/api/orders \
  -H "Content-Type: application/json" \
  -d '{"symbol":"NM.H100.US-EAST.2026-11","side":"buy","hours":100}'

HTTP/1.1 503 Service Unavailable
{
  "status": "unavailable",
  "error": "Live trading, swaps, and settlement are not available yet."
}

Errors and the path to a real contract#

Unknown method/path combinations fall through to HTTP 404 with an error of Not found. An unhandled exception, such as an upstream failure outside the price proxy guard, returns HTTP 400 with the exception message. OPTIONS receives a 204 response. The scaffold does not define a stable typed error taxonomy or a complete cross-origin API policy.

Before any production integration, define validated and versioned request schemas, protected server-owned fields, durable state, authenticated account authority, idempotency keys, limits and audit events. Add explicit transaction receipts for signed actions. The architecture document suggests future /v1 discovery and evidence services, but those endpoints are not implemented in server/api.js.

• Run the local examples ↗
• Review the intended service boundaries ↗