SDK Reference

BSP provides official SDKs to streamline integration. Both bsp-sdk (TypeScript) and bsp-sdk (Python) share the exact same architectural principles and class names.

TIP

The examples below use TypeScript syntax, but the Python equivalent is structurally identical, following synchronous or async/await patterns native to Python.

Core Clients

BSPClient

The primary entry point for the SDK. It handles connecting to Arweave, signing transactions, and managing identity.

import { BSPClient } from 'bsp-sdk';

// Initialize a client for an Institution (IEO)
const client = new BSPClient({
  domain: "fleury.bsp",
  privateKey: process.env.BSP_PRIVATE_KEY,
  environment: "mainnet" // or "testnet"
});

Creating Records

BioRecordBuilder

Used to construct immutable, schema-valid data objects before submission.

import { BioRecordBuilder } from 'bsp-sdk';

const builder = new BioRecordBuilder(client);

const record = builder
  .setBiomarker("BSP-LA-001") // hs-CRP
  .setValue(0.42)
  .setUnit("mg/L")
  .setCollectionTime("2026-02-26T08:30:00Z")
  .setSource("fleury.bsp") // automatically signed
  .build();
  
// Validation happens automatically on .build()

Network Operations

submitRecords()

Submits one or more BioRecords to a target BEO. Requires a valid ConsentToken.

const response = await client.submitRecords({
  targetBeo: "andre.bsp",
  records: [record1, record2],
  consentToken: "token-uuid-abc123"
});

console.log(response.transactionId); // Arweave TX ID
console.log(response.status); // "SUCCESS"

readRecords()

Fetches decrypted BioRecords from a BEO, scoped by the provided consent.

const results = await client.readRecords({
  targetBeo: "andre.bsp",
  consentToken: "token-uuid-def456",
  filter: {
    categories: ["BSP-LA", "BSP-CV"],
    period: {
      from: "2025-01-01T00:00:00Z",
      to: "2026-01-01T00:00:00Z"
    }
  }
});

console.log(`Retrieved ${results.records.length} records.`);

Access Control

issueConsentToken()

(BEO Holders Only). Issues a new token authorizing an IEO.

const token = await client.access.issueConsentToken({
  ieoDomain: "dr-carlos.bsp",
  scope: {
    intents: ["READ_RECORDS"],
    categories: ["BSP-CV"],
    period: { from: null, to: null } // All history
  },
  expiresInDays: 30
});

verifyToken()

(Target IEOs). Verifies if a token is valid for a specific action before attempting network transmission.

const check = await client.access.verifyToken({
  beoDomain: "andre.bsp",
  token: "token-uuid",
  intent: "SUBMIT_RECORD"
});

if (!check.valid) {
  throw new Error(`Consent invalid: ${check.reason}`); // e.g., "TOKEN_EXPIRED"
}

---

BEO Management

BEOClient

Manage Biological Entity Objects — create, lock, unlock, rotate key, destroy.

const beoClient = new BEOClient(config)

// Create
const { beo, private_key, seed_phrase } = await beoClient.create({ domain: 'andre.bsp' })

// Lock / Unlock
await beoClient.lock(beoId)
await beoClient.unlock(beoId)

// Rotate key
await beoClient.rotateKey(beoId, newSeedHex)

// Destroy (LGPD/GDPR right to erasure — irreversible)
await beoClient.destroy(beoId)

// Request Social Recovery
await beoClient.requestRecovery(beoId, newPublicKey)

---

IEO Management

IEOClient

Manage Institutional Entity Objects after creation — lock, unlock, rotate key, update contacts, destroy.

const ieoClient = new IEOClient(config)

// Read
const ieo = await ieoClient.get(ieoId)
const ieo = await ieoClient.resolve('fleury.bsp')
const { ieos } = await ieoClient.list({ type: 'LAB', status: 'ACTIVE' })

// Lock / Unlock
await ieoClient.lock(ieoId)
await ieoClient.unlock(ieoId)

// Rotate key
await ieoClient.rotateKey(ieoId, newSeedHex)

// Update contacts
await ieoClient.updateContacts(ieoId, { apiEndpoint: 'https://...', webhookUrl: '...' })

// Destroy (irreversible)
await ieoClient.destroy(ieoId)

// Verify certification
const { certified, level } = await ieoClient.verifyCertification(ieoId)

IEOBuilder

Register new institutions on the protocol.

const builder = new IEOBuilder({
  domain: 'fleury.bsp',
  name: 'Fleury Laboratórios',
  ieo_type: 'LAB',
  jurisdiction: 'BR',
  legal_id: '60.840.055/0001-31',
  contact: 'bsp@fleury.com.br',
}, config)

const { ieo, private_key, seed_phrase } = await builder.register()