Nerave SDK Documentation

Nerave solves the B2B trust deficit in Africa by ensuring contractors get paid when milestones are met, and buyers are protected if work isn't delivered. The SDK allows you to embed this trust directly into your own marketplaces, SaaS, or freelance platforms without dealing with Web3 complexities.

Install the SDK via npm, yarn, or pnpm. The package includes built-in TypeScript definitions.

npm install nerave-sdk

You must initialize the SDK with your Secret API Key. You can pass it directly or let the SDK auto-load it from your `.env` file via NERAVE_API_KEY.

import { Nerave } from 'nerave-sdk';
import 'dotenv/config';

// Option 1: Implicitly loads process.env.NERAVE_API_KEY
const nerave = new Nerave({});

// Option 2: Explicit initialization
const nerave = new Nerave({
  apiKey: 'pk_test_your_secret_key',
  // baseUrl: 'https://nerave.onrender.com' // Optional target URL
});

Agreements are the core entity. When you create an agreement, a secure smart escrow contract is instantly deployed on the Ethereum blockchain behind the scenes.

Creating an Agreement

Define the total transaction amount and split it across deliverables (milestones).

const agreement = await nerave.agreements.create({
  contractorId: 'uuid-of-developer',
  totalAmount: 1000,
  milestones: [
    { title: 'UX Research & Wireframing', amount: 300 },
    { title: 'Frontend Development', amount: 700 }
  ]
});

console.log(agreement.data.id); // e.g., "AGR-1092"

Checking Agreement Status

Poll the agreement to sync the local state with the on-chain data.

const state = await nerave.agreements.getStatus("AGR-1092");

console.log(state.totalAmount); 
console.log(state.milestones[0].disbursed); // false (pending)

Funds are only unlocked and disbursed to the contractor's Interswitch account when milestones are mutually confirmed.

Confirming a Milestone

As a standard B2B transaction requires mutual consent, both the CLIENT and the CONTRACTOR must hit this endpoint. Upon the second confirmation, Nerave automatically routes the funds via Interswitch.

// The client signs off on the "UX Research" milestone
await nerave.milestones.confirm({
  agreementId: "AGR-1092",
  milestoneId: 0, // Array index of the milestone
  role: 'CLIENT'
});

// Once the contractor also calls confirm(..., role: 'CONTRACTOR'),
// the Smart Contract instantly releases funds to Interswitch.