@valuete/sdk

Official JavaScript/TypeScript SDK for third-party platforms integrating with the Valuete Bitcoin-backed P2P lending API.

Install

npm install @valuete/sdk
# or link locally during development:
cd valuete-sdk && npm install && npm run build

Quick start

import {
  initializeLender,
  initializeBorrower,
  createTradingPair,
} from "@valuete/sdk";

// Preferred: separate lender / borrower credentials (must not be identical)
const { lender, borrower } = createTradingPair({
  baseUrl: "https://api.valuete.in",
  lenderApiKey: process.env.VALUETE_LENDER_API_KEY,
  borrowerApiKey: process.env.VALUETE_BORROWER_API_KEY,
});

// Or role helpers:
const lenderSdk = initializeLender({
  baseUrl: "https://api.valuete.in",
  apiKey: process.env.VALUETE_LENDER_API_KEY,
});
const borrowerSdk = initializeBorrower({
  baseUrl: "https://api.valuete.in",
  apiKey: process.env.VALUETE_BORROWER_API_KEY,
});

// Individual users (email/password, no platform API key):
// const borrower = await ValueteBorrower.fromEmailPassword({ baseUrl, email, password });

await lenderSdk.auth.loginWithoutPassword({ email: "[email protected]" });

Trading rules: Users from the same third-party client cannot trade with each other. Use keys from different clients, or an Individual (email/password) on one side. See valuete-backend/docs/TRADING_RULES_AND_BLACKLISTS.md.

Legacy single-instance init

import { ValueteSDK } from "@valuete/sdk";

const sdk = ValueteSDK.create({
  baseUrl: "https://api.valuete.in",
  apiKey: process.env.VALUETE_PLATFORM_API_KEY, // full / legacy key
});

Happy path flow (third-party integration)

The LendingHappyPathFlow orchestrator runs the full lend-offer lifecycle with two authenticated clients (lender + borrower). Pass different lenderApiKey and borrowerApiKey.

sequenceDiagram
  participant TP as Third Party App
  participant L as Lender (SDK)
  participant B as Borrower (SDK)
  participant API as Valuete API

  TP->>L: connect()
  TP->>B: connect()
  L->>API: POST /offers (lend offer)
  B->>API: POST /offers/:id/show-interest
  L->>API: POST /offers/:id/accept-interest
  Note over API: Trade created & started
  B->>API: POST /trades/:id/multisig/verify
  L->>API: POST /trades/:id/multisig/verify
  L->>API: POST /trades/:id/contracts/create
  B->>API: POST /trades/:id/origination-fee/pay
  B->>API: POST /trades/:id/bitcoin/deposit
  L->>API: POST /trades/:id/bitcoin/verify
  L->>API: POST /trades/:id/funds/transfer
  B->>API: POST /trades/:id/funds/received
  loop Each repayment
    B->>API: POST /trades/:id/repayments/:rid/pay
    L->>API: POST /trades/:id/repayments/:rid/acknowledge
  end
  B->>API: POST /trades/:id/margin-call/upload-psbt
  L->>API: POST /trades/:id/bitcoin/send
  B->>API: POST /trades/:id/bitcoin/acknowledge
  B->>API: POST /trades/:id/ratings
  L->>API: POST /trades/:id/ratings

Steps

| Step | Method | Actor | API | | ---- | ------------------------------- | -------- | -------------------------------------- | | 1 | connect() | Both | POST /auth/login | | 2 | createOffer() | Lender | POST /offers | | 3 | showInterest() | Borrower | POST /offers/:id/show-interest | | 4 | acceptInterestAndStartTrade() | Lender | POST /offers/:id/accept-interest | | 5 | confirmMultisig() | Both | POST /trades/:id/multisig/verify | | 6 | generateContract() | Lender | POST /trades/:id/contracts/create | | 7 | payOriginationFee() | Borrower | POST /trades/:id/origination-fee/pay (auto-skipped for integration platform trades) | | 8 | submitCollateral() | Borrower | POST /trades/:id/bitcoin/deposit | | 9 | confirmCollateral() | Lender | POST /trades/:id/bitcoin/verify | | 10 | transferFunds() | Lender | POST /trades/:id/funds/transfer | | 11 | confirmFunds() | Borrower | POST /trades/:id/funds/received | | 12 | processRepayments() | Both | repayments pay + acknowledge | | 13 | uploadBorrowerPSBT() | Borrower | POST /trades/:id/margin-call/upload-psbt | | 14 | sendBitcoinToBorrower() | Lender | POST /trades/:id/bitcoin/send | | 15 | acknowledgeBitcoinReceipt() | Borrower | POST /trades/:id/bitcoin/acknowledge | | 16 | submitRatings() | Both | POST /trades/:id/ratings |

Example

import { LendingHappyPathFlow } from "@valuete/sdk";

const flow = new LendingHappyPathFlow({
  baseUrl: "http://localhost:5000",
  apiKey: process.env.VALUETE_PLATFORM_API_KEY!,
  credentials: {
    lender: {
      email: "[email protected]",
      password: "...",
      multisigXpub: "xpub...",
    },
    borrower: {
      email: "[email protected]",
      password: "...",
      multisigXpub: "xpub...",
    },
  },
  offer: {
    offer: {
      offerType: "lend",
      currency: "INR",
      minAmount: 50000,
      maxAmount: 200000,
      interestRate: 12,
      loanDuration: 12,
      repaymentType: 1,
      ltv: 70,
      requiresLawyer: false,
      demo: true,
    },
    loanAmount: 100000,
  },
  payments: {
    originationFeeMethod: "v-tokens",
    collateral: { transactionId: "btc-tx-id", amount: 0.05 },
    fundTransfer: {
      transferMethod: "bank_transfer",
      transactionReference: "NEFT123",
      screenshotPath: "uploads/.../proof.png", // from POST /upload
    },
  },
  onStep: ({ step, actor }) => console.log(`${actor}: ${step}`),
});

await flow.connect();
await flow.createOffer();
// ... run each step, or await flow.runAll() for automated demos

See examples/happy-path.ts for a full script.

SDK modules

| Module | Purpose | | ------------ | --------------------------------- | | auth | Login, profile, multisig xpub | | offers | Create, browse, interest flow | | trades | Start, accept, multisig verify | | contracts | Generate & signing links | | bitcoin | Rates, deposit, verify, return collateral | | marginCall | PSBT upload during cooling / closure | | payments | Origination fee, fund transfer | | repayments | Schedule, pay, acknowledge | | ratings | Submit trade ratings | | upload | File upload for proofs |

Borrow-offer variant

When the borrower posts the offer:

1. Borrower: sdk.offers.create({ offerType: "borrow", loanAmount: ... })
2. Use flow.startBorrowOfferTrade(offerId) instead of steps 2–4
3. Continue from confirmMultisig() onward

Requirements

• Node.js 18+ (native fetch)
• Both users must have multisigXpub set on profile before trading
• Fund transfer requires a screenshot path from POST /upload

Related docs

| Document | Description | | -------------------------------------------------------------------- | ------------------------------------- | | Partner Quickstart | Start here — integrate in one day | | Happy Path Flow | Full trade lifecycle | | Execution Plan | SDK roadmap & phases | | All docs | Documentation index | | API Reference | Complete REST API | | API Keys | Platform isolation |