Aurellion Core API Contract

🏠 Home > Public API > Aurellion Core API Contract

HTTP contract for the aurellion-core read API that exposes public order and node detail endpoints.

Production base URL: https://prod-aurellion-core.up.railway.app

Source of truth: aurellion-core/src/public-api/ in the monorepo.

---

Overview

The public API is a small Fastify service deployed separately from the frontend and indexer. It provides:

• health and readiness probes
• public order detail by orderId
• public node detail by nodeId

All order and node identifiers must be bytes32 hex strings:

^0x[a-fA-F0-9]{64}$

---

Base URL

---

Authentication

By default, the API is public.

If API key mode is enabled, clients must send:

x-api-key: <key>

Auth mode is controlled by runtime environment variables:

PUBLIC_API_AUTH_MODE=public
# or
PUBLIC_API_AUTH_MODE=api_key

PUBLIC_API_KEYS=key-1,key-2
# fallback supported:
API_KEYS=key-1,key-2

Auth Error Contract

---

Rate Limiting

Each endpoint is rate-limited per client IP.

Every response includes:

x-rate-limit-limit: <number>
x-rate-limit-remaining: <number>
x-rate-limit-reset: <unix-seconds>
vary: x-api-key

Rate-limit errors:

---

Endpoints

`GET /health`

Health probe for Railway and external uptime checks.

Response

{
  "status": "ok"
}

`GET /ready`

Readiness probe.

Response

{
  "status": "ready"
}

`GET /api/v1/orders/:orderId`

Fetches a public order view with expanded journey data.

Path Parameters

Success Response

Cache policy:

cache-control: public, max-age=10, s-maxage=10, stale-while-revalidate=30

Body:

{
  "data": {
    "orderId": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcd",
    "orderSource": "unified",
    "token": "0x1111111111111111111111111111111111111111",
    "tokenId": "123",
    "tokenQuantity": "5",
    "price": "1000",
    "txFee": "10",
    "buyer": "0x2222222222222222222222222222222222222222",
    "seller": "0x3333333333333333333333333333333333333333",
    "status": "created",
    "contractualAgreement": "",
    "isP2P": false,
    "createdAt": 1234567890,
    "journeyIds": [
      "0x4444444444444444444444444444444444444444444444444444444444444444"
    ],
    "nodes": [
      "0x5555555555555555555555555555555555555555555555555555555555555555"
    ],
    "journeys": [
      {
        "journeyId": "0x4444444444444444444444444444444444444444444444444444444444444444",
        "status": "pending",
        "sender": "0x6666666666666666666666666666666666666666",
        "receiver": "0x7777777777777777777777777777777777777777",
        "driver": "0x8888888888888888888888888888888888888888",
        "journeyStart": "0",
        "journeyEnd": "0",
        "bounty": "10",
        "eta": "20",
        "parcelData": {
          "startLocation": { "lat": "0", "lng": "0" },
          "endLocation": { "lat": "1", "lng": "1" },
          "startName": "A",
          "endName": "B"
        }
      }
    ]
  }
}

Error Responses

`GET /api/v1/nodes/:nodeId`

Fetches a public node view including sellable and custody balances.

Path Parameters

Success Response

Cache policy:

cache-control: public, max-age=15, s-maxage=15, stale-while-revalidate=60

Body:

{
  "data": {
    "nodeId": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "owner": "0x1111111111111111111111111111111111111111",
    "status": "Active",
    "validNode": true,
    "location": {
      "addressName": "Warehouse A",
      "lat": "12.34",
      "lng": "56.78"
    },
    "assets": [
      {
        "token": "0x2222222222222222222222222222222222222222",
        "tokenId": "12",
        "price": "1000",
        "capacity": "10",
        "sellableQuantity": "7",
        "custodyQuantity": "9"
      }
    ]
  }
}

Error Responses

---

Shared Response Shapes

Success Envelope

{
  "data": {}
}

Error Envelope

{
  "error": {
    "code": "SOME_ERROR_CODE",
    "message": "Human readable message"
  }
}

---

Schemas

`PublicOrderDto`

`PublicJourneyDto`

`PublicNodeDto`

`PublicNodeAssetDto`

---

Example Requests

curl https://prod-aurellion-core.up.railway.app/health

curl https://prod-aurellion-core.up.railway.app/api/v1/orders/<orderId>

curl https://prod-aurellion-core.up.railway.app/api/v1/nodes/<nodeId>

curl \
  -H 'x-api-key: <key>' \
  https://prod-aurellion-core.up.railway.app/api/v1/orders/<orderId>

---

Operational Notes

• The service binds to PORT automatically in Railway.
• x-forwarded-for is used for rate limiting when present.
• The API is read-only and intended for public integration and discovery use cases.