NTS Platform – Quickstart

This quickstart shows how to talk to the live NTS APIs from any HTTP‑capable client.
It focuses on two services:

• Allocator API – submit household optimization jobs and fetch results.
• OMS API – send trading commands into the OMS command stream.

All examples assume you already have:

• A base URL for your deployment (examples use http://localhost).
• An API token that you pass in the x-api-token header.

---

1. Environment & Authentication

Every request must include:

x-api-token: <your-token>

In examples below we’ll use:

• ALLOC_BASE – base URL for the allocator API.
• OMS_BASE – base URL for the OMS API.
• API_TOKEN – your token.

Example shell exports:

export ALLOC_BASE="http://localhost:8082"
export OMS_BASE="http://localhost:8081"
export API_TOKEN="devtoken123"

---

2. Allocator API – Hello World

The allocator service lets you submit long‑running optimization jobs and download a PPTX report when they finish.

2.1 Submit a job (curl)

curl -X POST "$ALLOC_BASE/allocator/jobs"   -H "Content-Type: application/json"   -H "x-api-token: $API_TOKEN"   -d '{
    "job": {
      "household_id": "demo-house",
      "objective": "custom",
      "n_sims": 3000,
      "local_iters": 4,
      "grid_step": 0.10,
      "notes": "Quickstart demo"
    },
    "tenant": "nts",
    "dry_run": false
  }'

Typical response:

{
  "accepted": true,
  "job_id": "1764792929054-0",
  "idem_key": "d1c1f1f3...",
  "message": "Queued"
}

Save job_id – you’ll use it to poll status and fetch the report.

2.2 Poll job status

curl -s "$ALLOC_BASE/allocator/jobs/1764792929054-0"   -H "x-api-token: $API_TOKEN"

Response shape:

{
  "job_id": "1764792929054-0",
  "status": "RUNNING",
  "created_at": "...",
  "updated_at": "...",
  "artifact_s3_key": null,
  "params": {
    "n_sims": 3000,
    "local_iters": 4,
    "grid_step": 0.1,
    "start_crt": 8500000.0,
    "start_tax": 7500000.0,
    "years": 30,
    "payout_rate": 0.085
  }
}

Possible status values:

• PENDING
• RUNNING
• DONE
• ERROR

2.3 Download the PPTX report

When status is DONE, you can request a presigned report URL:

curl -s "$ALLOC_BASE/allocator/artifacts/1764792929054-0/report"   -H "x-api-token: $API_TOKEN"

Example response:

{
  "job_id": "1764792929054-0",
  "report_url": "https://s3-region.amazonaws.com/nts-household-artifacts/jobs/1764.../report.pptx?X-Amz-Algorithm=..."
}

Download directly with curl:

curl -o report.pptx "$(curl -s "$ALLOC_BASE/allocator/artifacts/1764792929054-0/report"   -H "x-api-token: $API_TOKEN" | jq -r .report_url)"

---

3. OMS API – Ping & Commands

The OMS API writes signed command envelopes into oms:commands in Redis.
Downstream, ibgatekeeper consumes those commands and talks to IBKR.

3.1 Health check

curl -s "$OMS_BASE/healthz"

Response:

{"status":"ok","version":"0.1.0"}

3.2 Ping

curl -X POST "$OMS_BASE/oms/ping"   -H "Content-Type: application/json"   -H "x-api-token: $API_TOKEN"   -d '{"echo": "hello-nts"}'

If accepted, you’ll see:

{
  "status": "enqueued",
  "message_id": "1764...",
  "idem_key": "oms:..."
}

3.3 Next steps

For trading‑related endpoints (/oms/orders, /oms/flatten) and detailed allocator job schema, see:

• allocator_api.md
• oms_api.md
• concepts_household_optimizer.md