VALid SDK (@valid/sdk)

Read-only partner SDK for wallet teams to fetch handleName exchange before user confirms a transaction.

What It Does

• Sends selfAddress + counterpartyAddress to VALid backend.
• Returns:
  • self handleName
  • peer handleName (or No VALid)
  • exchange text: [VALid: self<>peer]

What It Does NOT Do

• No signing
• No key access
• No transaction broadcast
• No wallet state mutation

Install

npm i @valid/sdk

Usage

import { createValidSdk } from "@valid/sdk";

const sdk = createValidSdk({
  baseUrl: "https://valid-valid.onrender.com",
  apiKey: "<optional-sdk-key>",
  timeoutMs: 8000,
});

const result = await sdk.validateCounterparty({
  selfAddress: "0x53cB8e836a17Fd858d31180152721Fd9F7C67A42",
  counterpartyAddress: "0xf677EDf22797bc5c82ecEB9e192847B5A1acEC0c",
  walletName: "MetaMask",
  chainId: 1,
});

console.log(result.exchange.text); // [VALid: tomlammers<>tgl]

Backend Contract

POST /api/sdk/validate-counterparty

Request:

{
  "selfAddress": "0x...",
  "counterpartyAddress": "0x...",
  "walletName": "MetaMask",
  "chainId": 1
}

Success response:

{
  "ok": true,
  "status": "verified",
  "chainId": 1,
  "self": {
    "walletAddress": "0x...",
    "walletName": "MetaMask",
    "handleName": "tomlammers",
    "registered": true
  },
  "peer": {
    "walletAddress": "0x...",
    "walletName": "Phantom",
    "handleName": "tgl",
    "registered": true
  },
  "exchange": {
    "text": "[VALid: tomlammers<>tgl]",
    "updatedAt": "2026-03-14T00:00:00.000Z"
  }
}

If self wallet is not registered:

• status = "self_not_registered"
• exchange.text = null

API Key (Optional)

Set server env:

• VALID_SDK_API_KEY=<secret>

If set, client must send header:

• x-valid-sdk-key: <secret>