Quickstart

Get up and running with the Orbitport SDK in minutes. This guide covers installation, basic usage, and understanding the response format.

Install the SDK

Using npm:

npm i @spacecomputer-io/orbitport-sdk-ts

Or using yarn:

yarn add @spacecomputer-io/orbitport-sdk-ts

Initialize with API credentials

If you have API credentials, the SDK will use the Orbitport API first and automatically fall back to IPFS if the API is unavailable:

import { OrbitportSDK } from "@spacecomputer-io/orbitport-sdk-ts";

const sdk = new OrbitportSDK({
  config: {
    clientId: "your-client-id",
    clientSecret: "your-client-secret",
  },
});

const result = await sdk.ctrng.random();
console.log(result.data.data); // The cTRNG value

Initialize without credentials (IPFS only)

You can use the SDK without any credentials to access the public IPFS beacon:

import { OrbitportSDK } from "@spacecomputer-io/orbitport-sdk-ts";

const sdk = new OrbitportSDK({ config: {} });

const result = await sdk.ctrng.random();
console.log(result.data.data); // The cTRNG value from IPFS

Get a random value

Once initialized, call sdk.ctrng.random() to get a cTRNG value:

const result = await sdk.ctrng.random();
console.log(result.data.data);   // Hex string of random data
console.log(result.data.src);    // Source: "trng", "rng", or "ipfs"
console.log(result.success);     // true if successful

Response structure

All random() calls return a ServiceResult<CTRNGResponse>:

interface ServiceResult<CTRNGResponse> {
  data: CTRNGResponse;
  metadata: {
    timestamp: number;
    request_id?: string;
  };
  success: boolean;
}

interface CTRNGResponse {
  service: string;    // "trng", "rng", or "ipfs-beacon"
  src: string;        // "trng", "rng", or "ipfs"
  data: string;       // The random value as a hex string
  signature?: {
    value: string;
    pk: string;
  };                  // Present only for API responses
  timestamp?: string;
  provider?: string;
}

The signature field is only present when the value comes from the API (not IPFS). It contains the satellite's cryptographic signature over the random data.

Complete example

import { OrbitportSDK } from "@spacecomputer-io/orbitport-sdk-ts";

async function main() {
  const sdk = new OrbitportSDK({
    config: {
      // Optional: add credentials for API access
      // clientId: "your-client-id",
      // clientSecret: "your-client-secret",
    },
  });

  try {
    const result = await sdk.ctrng.random();
    console.log("Random value:", result.data.data);
    console.log("Source:", result.data.src);
  } catch (error) {
    console.error("Error:", error);
  }
}

main();

Next steps

SDK Authentication -- Configure API credentials and manage tokens.
SDK IPFS Beacon -- Access historical blocks, select specific indices, and use custom beacons.
SDK Error Handling -- Handle errors and configure retry behavior.
SDK Advanced Configuration -- Customize timeouts, IPFS gateways, and debug mode.
Cosmic Randomness -- Understand where the randomness comes from.
Orbitport Architecture -- Learn how the system works end to end.