Apostolos Protocol
Documentation

Apostolos is a fully on-chain cultural data protocol for encoding, preserving, and exchanging digital artifacts as cryptographic objects. This documentation covers the protocol architecture, SDK, and integration guides.

npm install @apostolos/sdk

import { Apostolos } from "@apostolos/sdk";

const client = new Apostolos({
  network: "mainnet",       // or "testnet"
  privateKey: process.env.PRIVATE_KEY,
});

const artifact = await client.encode({
  data: fs.readFileSync("./artwork.png"),
  mimeType: "image/png",
  metadata: {
    title: "Genesis Object #001",
    creator: "0xYourAddress",
  },
});

console.log(artifact.id); // on-chain artifact ID

npm install @apostolos/sdk

yarn add @apostolos/sdk

pnpm add @apostolos/sdk

APOSTOLOS_NETWORK=mainnet
APOSTOLOS_PRIVATE_KEY=your_private_key_here
APOSTOLOS_RPC_URL=https://rpc.apostolos.xyz

const artifact = await client.encode({
  data: Buffer,           // raw artifact bytes
  mimeType: string,       // MIME type of the artifact
  metadata: {
    title: string,
    creator: string,      // wallet address
    tags?: string[],
  },
  privacy?: "public" | "zk-shielded",  // default: "public"
});

// Returns:
// {
//   id: string,          // on-chain artifact ID
//   txHash: string,      // inscription transaction hash
//   size: number,        // encoded byte size
//   timestamp: number,
// }

const proof = await client.transfer({
  artifactId: "art_abc123",
  recipient: "0xRecipientAddress",
  zkMode: true,           // generates ZK proof of ownership
});

// proof.receipt on-chain transfer receipt
// proof.zkProof verifiable ZK proof for recipient

const isOwner = await client.verify({
  artifactId: "art_abc123",
  proof: proof.zkProof,
});

console.log(isOwner); // true

// Gating an artifact with x402
const gate = await client.pay.createGate({
  artifactId: "art_abc123",
  price: "0.001",          // in protocol token
  currency: "USDC",
  access: "single-view",   // or "permanent"
});

// Accessing a gated artifact
const access = await client.pay.unlock({
  gateId: gate.id,
  payer: "0xYourAddress",
});

console.log(access.contentUrl);

const history = await client.provenance("art_abc123");

// Returns array of events:
// [
//   { event: "inscribed", address: "0x...", timestamp: ... },
//   { event: "transferred", from: "0x...", to: "0x...", ... },
//   { event: "licensed", licensee: "0x...", ... },
// ]

npm install @apostolos/sdk

import { Apostolos, ArtifactMetadata, EncodeResult } from "@apostolos/sdk";

const result = await client.encode({
  data: fs.readFileSync("artifact.mp4"),
  mimeType: "video/mp4",
  metadata: { title: "Archive Reel #01", creator: "0xYour" },
});

const tx = await client.transfer({
  artifactId: "art_abc123",
  recipient: "0xRecipient",
  zkMode: true,
});

const valid = await client.verify({
  artifactId: "art_abc123",
  proof: zkProof,
});

// Create gate
const gate = await client.pay.createGate({
  artifactId: "art_abc123",
  price: "0.50",
  currency: "USDC",
  access: "permanent",
});

// Unlock
const grant = await client.pay.unlock({
  gateId: gate.id,
  payer: "0xYourAddress",
});

type Artifact = {
  id: string;                  // unique on-chain artifact ID
  dataHash: string;            // keccak256 of raw artifact bytes
  segments: Segment[];         // on-chain encoded data segments
  metadata: ArtifactMetadata;  // title, creator, mimeType, tags
  ownershipCommitment: string; // ZK ownership commitment hash
  provenanceRoot: string;      // merkle root of transfer history
  createdAt: number;           // block timestamp of inscription
};

type ArtifactMetadata = {
  title: string;
  creator: string;          // wallet address
  mimeType: string;
  tags?: string[];
};