SDK Reference

The mnemox402 SDK provides a comprehensive TypeScript interface for interacting with the protocol, supporting both publisher and consumer workflows.

Official SDK Repository

The official mnemox402 SDK is available on GitHub:

Repository: https://github.com/mnemox402/mnemox402

The SDK is written in TypeScript and enables AI agents to:

• Store vector embeddings on IPFS (InterPlanetary File System)

• Sell memory shards to other agents via the marketplace

• Purchase relevant memories using similarity search

• Pay for data using the X402 protocol (HTTP 402 Payment Required)

Installation

Clone the repository and install dependencies:

git clone https://github.com/mnemox402/mnemox402.git
cd mnemox402
npm install
npm run build

Quick Start

import { Mnemox402, cosineSimilarity } from './src/index';
import { ethers } from 'ethers';

// Initialize SDK with wallet signer
const provider = new ethers.JsonRpcProvider('https://rpc.example.com');
const signer = new ethers.Wallet(process.env.PRIVATE_KEY!, provider);

const sdk = new Mnemox402({
  signer,
  vaultConfig: {
    ipfsGateway: 'https://ipfs.io/ipfs/',
  },
});

// Create a vector embedding (example)
const myVector = [0.1, 0.2, 0.3, 0.4, 0.5];

// List memory shard for sale
const listingId = await sdk.marketplace.listMemoryShard(
  myVector,
  ethers.parseEther('0.1').toString(), // 0.1 protocol assets
  await signer.getAddress(),
  {
    description: 'AI agent memory about user preferences',
    category: 'user-data',
  }
);

console.log(`Listed memory shard: ${listingId}`);

// Search for similar memories
const results = await sdk.marketplace.searchListings(myVector, {
  minSimilarity: 0.8,
  maxPrice: ethers.parseEther('1.0').toString(),
});

// Purchase a memory shard
if (results.length > 0) {
  const purchasedVector = await sdk.marketplace.buyMemoryShard(
    results[0].listing.id,
    await signer.getAddress()
  );
  
  // Calculate similarity
  const similarity = cosineSimilarity(myVector, purchasedVector);
  console.log(`Purchased memory with similarity: ${similarity}`);
}

X402 Payment Flow

The SDK handles HTTP 402 Payment Required responses automatically:

// Make a request that requires payment
  const response = await fetch('https://api.mnemox402.io/memory/123');

if (response.status === 402) {
  // Handle payment flow
  const authHeader = await sdk.x402.processPaymentFlow(response, response.url);
  
  // Retry request with payment proof
  const paidResponse = await fetch('https://api.mnemox402.io/memory/123', {
    headers: {
      'Authorization': authHeader,
    },
  });
  
  const data = await paidResponse.json();
}

API Reference

Mnemox402

Main SDK class that provides access to all functionality.

Constructor

new Mnemox402(config?: Mnemox402Config)

Methods

• setSigner(signer: ethers.Signer): Update the wallet signer for payments

X402Client

Handles HTTP 402 Payment Required protocol.

Methods

• handle402Error(response: Response): Parse 402 response and extract payment details

• signPayment(paymentDetails, requestUrl): Sign a payment transaction

• createAuthHeader(proof): Generate Authorization header for retry

• processPaymentFlow(response, requestUrl): Complete payment flow

Vault

Manages vector storage on IPFS.

Methods

• uploadVector(vector, metadata?): Upload vector to IPFS

• retrieveVector(cid): Retrieve vector from IPFS by CID

• findSimilarVectors(queryVector, threshold?, limit?): Search for similar vectors

Listing (Marketplace)

Marketplace for buying and selling memory shards.

Methods

• listMemoryShard(vector, price, seller, options?): List a memory shard for sale

• buyMemoryShard(listingId, buyer): Purchase a memory shard

• searchListings(queryVector, filters?): Search listings by similarity

• getListing(listingId): Get listing by ID

• getAllListings(): Get all active listings

Math Utilities

• cosineSimilarity(a, b): Calculate cosine similarity between vectors

• dotProduct(a, b): Calculate dot product

• vectorNorm(vector): Calculate vector magnitude

• normalizeVector(vector): Normalize vector to unit length

• euclideanDistance(a, b): Calculate Euclidean distance

Security

• All payments are signed with your private key using ethers.js

• Vectors can be encrypted before IPFS upload

• Payment proofs include nonces to prevent replay attacks

Network Support

mnemox402 supports multiple blockchain networks. Configure your provider accordingly:

const provider = new ethers.JsonRpcProvider('YOUR_RPC_URL');

Resources

• Website: https://mnemox402.cloud

• Twitter: https://x.com/mnemox402

License

MIT License - see LICENSE file for details.