Official Node.js SDK for the Floyd Blockchain API
npm install @tormentalabs/floyd-sdk

Official Node.js SDK for the Floyd Blockchain API.
- Full API coverage - Assets, Wallets, History, Blockchain status
- Auto-retry - Exponential backoff for transient failures
- Rate limit handling - Automatic queuing on 429 responses
- Pagination helpers - Async iterators for seamless pagination
- Idempotency - Auto-generated keys for safe retries
- Response caching - LRU cache for GET requests
- TypeScript - Full type definitions included
- Validators - Built-in CPF/CNPJ validation
``bash`
npm install @tormentalabs/floyd-sdk
`typescript
import { Floyd } from '@tormentalabs/floyd-sdk';
const floyd = new Floyd({
apiKey: process.env.FLOYD_API_KEY,
});
// Create an asset
const asset = await floyd.assets.create({
name: 'My Bike',
legalEntity: 'PF',
document: '12345678901',
chassisNumber: 'ABC123',
serialNumber: 'SN-001',
invoiceDate: '2025-01-15',
mileage: 0,
});
// Wait for blockchain confirmation
const confirmed = await floyd.assets.waitForConfirmation(asset.id, {
timeout: 120000,
onProgress: (status) => console.log(Status: ${status}),
});
console.log(Confirmed with tx: ${confirmed.blockchain.transactionHash});`
`typescript
// Auto-pagination with async iterator
for await (const asset of floyd.assets.listAll({ limit: 100 })) {
console.log(asset.name);
}
// Collect all into array
const allAssets = await floyd.assets.listAll().toArray();
// With progress tracking
const assets = await floyd.assets.listAll({
onProgress: ({ fetched, hasMore }) => {
console.log(Fetched ${fetched} assets, more: ${hasMore});`
}
}).toArray();
`typescript
const floyd = new Floyd({
apiKey: 'your-api-key',
baseUrl: 'https://api.floyd.example.com', // optional
// Retry configuration
retry: {
maxAttempts: 3,
backoff: 'exponential', // 'exponential' | 'linear' | 'fixed'
initialDelay: 1000,
maxDelay: 30000,
},
// Timeouts
timeout: {
request: 30000,
},
// Caching (GET requests only)
cache: {
enabled: true,
ttl: 60000,
maxSize: 100,
},
// Auto-generate idempotency keys
idempotency: {
autoGenerate: true,
keyPrefix: 'floyd_',
},
// Debug logging
debug: true,
});
`
`typescript
// CRUD
await floyd.assets.create({ ... });
await floyd.assets.get('asset-id');
await floyd.assets.list({ legalEntity: 'PF', limit: 50 });
await floyd.assets.update('asset-id', { mileage: 1000 });
await floyd.assets.delete('asset-id');
// Transfers
await floyd.assets.transfer('asset-id', {
name: 'New Owner',
legalEntity: 'PJ',
document: '12345678000199',
});
// Blockchain
await floyd.assets.verify('asset-id');
await floyd.assets.waitForConfirmation('asset-id');
// Accessories
await floyd.assets.attachAccessory('asset-id', 'acc-id', { name: 'GPS Tracker' });
await floyd.assets.detachAccessory('asset-id', 'acc-id');
`
`typescript`
await floyd.wallets.create({ userId: 'user-uuid' });
await floyd.wallets.get('user-id');
await floyd.wallets.getBalance('user-id');
await floyd.wallets.signMessage('user-id', { message: 'Hello' });
await floyd.wallets.signTypedData('user-id', { domain, types, value });
`typescript
await floyd.history.search({
assetId: 'asset-id',
eventType: 'TRANSFER',
fromDate: '2025-01-01',
});
// Auto-pagination
for await (const event of floyd.history.searchAll({ assetId: 'id' })) {
console.log(event.eventType);
}
`
`typescriptConnected: ${status.connected}, Block: ${status.latestBlock}
const status = await floyd.blockchain.status();
console.log();`
`typescript
import {
FloydError,
ValidationError,
NotFoundError,
RateLimitError
} from '@tormentalabs/floyd-sdk';
try {
await floyd.assets.get('invalid-id');
} catch (error) {
if (error instanceof NotFoundError) {
console.log('Asset not found');
} else if (error instanceof ValidationError) {
console.log('Validation errors:', error.details);
} else if (error instanceof RateLimitError) {
console.log(Rate limited, retry after ${error.retryAfter}s);`
}
}
`typescript
import { createMockClient, createMockAsset } from '@tormentalabs/floyd-sdk/testing';
const mockFloyd = createMockClient({
assets: {
get: async () => createMockAsset({ name: 'Test Bike' }),
},
});
const asset = await mockFloyd.assets.get('id');
// asset.name === 'Test Bike'
``
- @tormentalabs/floyd-webhooks - Webhook handling
- @tormentalabs/floyd-types - TypeScript definitions
- @tormentalabs/floyd-validators - Document validators
MIT