@railblock/opencommodity-sdk

Official TypeScript SDK for the OpenCommodity™ protocol, operated by Railblock. Provides a typed REST client, ethers v6 chain wrappers, and v2 webhook signature verification.

Install

npm i @railblock/opencommodity-sdk
# optional, for on-chain helpers
npm i ethers

Quickstart

import { OpenCommodityClient } from "@railblock/opencommodity-sdk";

const client = new OpenCommodityClient({ apiKey: process.env.OC_API_KEY! });

const stats = await client.stats.get();
for await (const c of client.commodities.iterate({ status: "verified" })) {
  console.log(c.gcid, c.name);
}

Webhook verification (v2)

import express from "express";
import { expressWebhook } from "@railblock/opencommodity-sdk/webhooks";

const app = express();
app.post(
  "/webhooks/opencommodity",
  express.raw({ type: "application/json" }),
  expressWebhook(process.env.OC_WEBHOOK_SECRET!),
  (req, res) => {
    // req.webhook is the parsed, verified payload
    res.sendStatus(200);
  },
);

Header scheme (v2):

| Header | Description | |---|---| | X-OpenCommodity-Signature | sha256=HMAC_SHA256(secret, "${ts}.${rawBody}") | | X-OpenCommodity-Timestamp | unix seconds | | X-OpenCommodity-Event | event name | | X-OpenCommodity-Delivery | UUID per attempt |

On-chain helpers

import { JsonRpcProvider, Wallet } from "ethers";
import { SalesEscrowContract } from "@railblock/opencommodity-sdk";

const provider = new JsonRpcProvider(process.env.RPC_URL);
const signer = new Wallet(process.env.PK!, provider);
const escrow = new SalesEscrowContract({ runner: signer, address: process.env.ESCROW_ADDR });

const sale = await escrow.getSale(42n);

Contracts that aren't deployed (address 0x0…0) throw NotDeployedError — pass { allowUndeployed: true } for local testing.

License

MIT