The IXO Matrix SDK provides encrypted data storage, secure messaging, and automated room management through IXO Matrix protocol integration. It enables developers to create secure, scalable, and well-integrated applications within the IXO Matrix ecosystem.

Overview

The IXO Matrix SDK is a comprehensive toolkit that enables developers to interact seamlessly with IXO Matrix servers and associated bot services. It provides capabilities for:

  • User profile management and authentication
  • Room creation and management
  • Automated bot-assisted room operations
  • State management and access control
  • Real-time communication features
  • Secure data handling across rooms

Key Features

Matrix Client

Provides the interface for standard IXO Matrix server interactions including media management, user profiles, and room operations

Room Bot

Automates IXO Matrix room management, with blockchain integration and membership handling

IXO Matrix State Bot

Manages IXO Matrix room state data, access controls, and configuration

Utilities

Helper functions for MXC URLs, validators, and IXO Matrix ecosystem tools

Installation

# Using npm
npm install @ixo/matrixclient-sdk

# Using yarn
yarn add @ixo/matrixclient-sdk

Quick Start

API Client

import { createMatrixApiClient } from "@ixo/matrixclient-sdk";

// Initialize API client
const client = await createMatrixApiClient({
  baseUrl: "https://matrix.ixo.world",
  accessToken: "YOUR_TOKEN"
});

// Upload media
const mxcUrl = await client.uploadMedia(
  file,
  { fileName: "data.json" }
);

// Update profile
await client.setDisplayName("User Name");
await client.setAvatarUrl(mxcUrl);

Room Bot

import { createMatrixRoomBotClient } from "@ixo/matrixclient-sdk";

// Initialize room bot
const bot = await createMatrixRoomBotClient({
  baseUrl: "https://matrix.ixo.world",
  accessToken: "BOT_TOKEN"
});

// Create entity room
const entityRoom = await bot.createEntityRoom({
  entityDid: "did:ixo:entity/123",
  name: "Entity Data Room",
  members: ["@alice:ixo.world", "@bob:ixo.world"]
});

// Handle invites
await bot.handleInvites();

IXO Matrix State Bot

The IXO Matrix State Bot component provides access to the IXO Matrix State Bot API, which enables management of room state and access control lists.

import { createMatrixStateBotClient } from "@ixo/matrixclient-sdk";

// Initialize IXO Matrix State Bot
const bot = await createMatrixStateBotClient({
  baseUrl: "https://matrix.ixo.world",
  accessToken: "BOT_TOKEN"
});

// Get room ACL
const acl = await bot.getRoomAcl(roomId);

// Update ACL
await bot.setRoomAcl(roomId, {
  allow: ["@alice:ixo.world"],
  deny: ["@malicious:ixo.world"]
});

// Get room state
const state = await bot.getRoomState(roomId);

Utilities

MXC Helpers

import { utils } from "@ixo/matrixclient-sdk";

// Convert MXC to HTTP URL
const httpUrl = utils.mxcUrlToHttp(
  "mxc://ixo.world/abc123",
  "https://matrix.ixo.world"
);

// Validate MXC URL
const isValid = utils.isMxcUri("mxc://ixo.world/abc123");

Validators

// Validate Matrix IDs
const isValidUserId = utils.isUserId("@alice:ixo.world");
const isValidRoomId = utils.isRoomId("!room:ixo.world");
const isValidAlias = utils.isAlias("#general:ixo.world");

Error Handling

400
error

Invalid request parameters

401
error

Invalid access token

403
error

Insufficient permissions

Use Cases

Real-Time Communication

Build secure messaging and real-time collaboration systems with end-to-end encryption

Data Rooms

Create and manage encrypted data storage rooms with controlled access for sensitive information

Automated Management

Implement bot-driven room and membership automation for scalable applications

Access Control

Define and enforce granular access permissions using ACLs for secure data governance

Best Practices

Follow these guidelines for secure and efficient IXO Matrix integration

Security

  • Use encrypted rooms for sensitive data
  • Implement proper access control
  • Rotate access tokens regularly
  • Validate all user inputs
  • Enable end-to-end encryption where appropriate
  • Regularly audit room access permissions

Performance

  • Batch state updates
  • Implement proper error handling
  • Cache room states
  • Monitor room sizes
  • Use appropriate SDK methods for bulk operations
  • Implement rate limiting for API calls

Next Steps

Room Guide

Learn room management

Bot Guide

Implement automation

Security Guide

Secure your rooms