@headlessoracle/client

Stop trading blind. Verify exchange status before every order with a cryptographically signed receipt that expires in 60 seconds.

TypeScript client for Headless Oracle V5 — typed wrappers for all endpoints, optional built-in signature verification, zero ambiguity about market state.

Installation

npm install @headlessoracle/client
# Optional: built-in receipt verification
npm install @headlessoracle/verify

Quick start

import { OracleClient } from '@headlessoracle/client'

const client = new OracleClient({ apiKey: 'ok_live_...' })

// Fetch a signed live receipt
const receipt = await client.getStatus('XNYS')

// Fail-closed: treat UNKNOWN as CLOSED
if (receipt.status !== 'OPEN') {
  throw new Error('Market not open — halting all execution')
}

With built-in verification

const client = new OracleClient({
  apiKey:    'ok_live_...',
  verify:    true,
  publicKey: '03dc27993a2c90856cdeb45e228ac065f18f69f0933c917b2336c1e75712f178',
})

// Throws OracleVerifyError if signature is invalid
const receipt = await client.getStatus('XNYS')

Batch queries

const batch = await client.getBatch(['XNYS', 'XNAS', 'XLON'])
for (const receipt of batch.receipts) {
  console.log(receipt.mic, receipt.status)
}

Schedule

const schedule = await client.getSchedule('XNYS')
console.log('Next open:', schedule.next_open)
console.log('Next close:', schedule.next_close)

API

| Method | Auth | Description | |--------|------|-------------| | getDemo(mic?) | No | Signed demo receipt (for testing) | | getStatus(mic?) | Yes | Signed live receipt | | getBatch(mics[]) | Yes | Signed receipts for multiple exchanges | | getSchedule(mic?) | No | Next open/close times | | listExchanges() | No | All supported exchanges | | getKeys() | No | Public key registry | | getHealth() | No | Oracle liveness probe |

Error handling

import { OracleClient, OracleError, OracleVerifyError } from '@headlessoracle/client'

try {
  const receipt = await client.getStatus('XNYS')
} catch (err) {
  if (err instanceof OracleError) {
    // HTTP error — err.statusCode, err.body
  } else if (err instanceof OracleVerifyError) {
    // Signature verification failed — err.reason
  }
}

Supported exchanges

| MIC | Exchange | Timezone | |-----|----------|----------| | XNYS | New York Stock Exchange | America/New_York | | XNAS | NASDAQ | America/New_York | | XLON | London Stock Exchange | Europe/London | | XJPX | Japan Exchange Group | Asia/Tokyo | | XPAR | Euronext Paris | Europe/Paris | | XHKG | Hong Kong Exchanges | Asia/Hong_Kong | | XSES | Singapore Exchange | Asia/Singapore |

License

MIT