BlueChips Documentation

Cryptographic provenance and consent verification for digital media

What are BlueChips Stamps?

BlueChips Stamps is a trust infrastructure layer that allows creators and platforms to prove the authenticity, identity, and consent of digital media through secure hardware-attested signatures.

The documentation is organized to support different personas:

Integrators who need to embed the API and webhooks.
SDK developers building native experiences.
Security & compliance teams reviewing the data flows.
Operations teams monitoring platform health.

Key Capabilities

Capability	Description
Device & Face Attestation	Hardware root-of-trust verification for supported mobile and desktop chipsets.
Cryptographic Consent Receipts	zk-SNARK compatible proof issuance with revocation support.
Media Provenance Chain	Hash-linked ledger tracking source media, edits, and reposts.
Soulbound Token Architecture	Non-transferable, revocable blockchain credentials anchored to permissioned ledger with public chain verification.
C2PA Compatibility	Native support for Content Provenance and Authenticity (C2PA) credentials and manifests.
Platform Integration	REST APIs, SDKs, and webhook events for moderation and trust workflows.

Getting Started

This guide walks through the minimum steps required to register a media stamp, verify it, and retrieve the associated consent receipt in the sandbox environment.

Prerequisites

A verified developer account on the BlueChips portal.
Sandbox API key with stamps.write and stamps.read scopes.
Node.js 18+ or Python 3.10+ installed locally.
curl for making HTTP requests.

1. Initialize a Project Workspace

mkdir bluechips-demo && cd bluechips-demo
python3 -m venv .venv
source .venv/bin/activate
pip install bluechips-stamps

Alternatively, install the JavaScript SDK:

npm init -y
npm install @bluechips/stamps

2. Capture or Upload Media

Collect the media asset, device identifier, and subject face image. Create SHA-512 hashes for the media and subject face.

shasum -a 512 video.mp4 | cut -d " " -f 1 > video.sha512
shasum -a 512 face.jpg | cut -d " " -f 1 > face.sha512

3. Create a Stamp via API

curl -X POST "https://sandbox.bluechips.com/v1/stamps/create" \
  -H "Authorization: Bearer $BLUECHIPS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "file_hash": "'"$(cat video.sha512)"'",
        "device_id": "ios-14a8d29a3f",
        "subject_face_hash": "'"$(cat face.sha512)"'",
        "consent_signed_at": "2025-10-15T14:00:00Z",
        "c2pa_manifest": {
          "claim_generator": "BlueChips/1.0",
          "assertions": [
            {
              "label": "c2pa.actions",
              "data": {
                "actions": [
                  {
                    "action": "c2pa.created",
                    "when": "2025-10-15T14:00:00Z"
                  }
                ]
              }
            }
          ]
        },
        "blockchain_options": {
          "network": "permissioned",
          "anchor_to_public": true,
          "public_chain": "ethereum-mainnet"
        },
        "metadata": {
          "platform": "OnlyFans",
          "creator_id": "user_7238",
          "location": "Los Angeles, CA"
        }
      }'

Response:

{
  "stamp_id": "bcstmp_01H93KQZG83FQ2Y4R8J0MCPW7X",
  "attestation": {
    "verified_device": true,
    "verified_subject": true,
    "hardware_proof": "0xabc123..."
  },
  "c2pa_validation": {
    "manifest_valid": true,
    "claim_signature_valid": true,
    "trust_chain_valid": true
  },
  "blockchain": {
    "token_id": "0x7f3e9a2b1c4d5e6f...",
    "network": "bluechips-permissioned",
    "contract_address": "0x1234567890abcdef...",
    "is_soulbound": true,
    "transferable": false,
    "revocable": true,
    "anchor_tx_hash": "0xdef456...",
    "anchor_chain": "ethereum-mainnet",
    "block_number": 18234567
  },
  "consent_receipt_url": "https://verify.bluechips.com/r/bcstmp_01H93KQZG83FQ2Y4R8J0MCPW7X"
}

4. Verify a Stamp

curl "https://sandbox.bluechips.com/v1/stamps/verify/bcstmp_01H93KQZG83FQ2Y4R8J0MCPW7X" \
  -H "Authorization: Bearer $BLUECHIPS_KEY"

The valid flag will be true when the provenance chain is intact, the device attestation passes, the face match score is greater than 0.95, and the blockchain token has not been revoked.

5. Retrieve Consent Receipt

curl "https://sandbox.bluechips.com/v1/consent/bcstmp_01H93KQZG83FQ2Y4R8J0MCPW7X" \
  -H "Authorization: Bearer $BLUECHIPS_KEY" \
  -o consent.pdf

The receipt is a notarized PDF containing the consent signer, timestamp, and cryptographic proof bundle.

6. Promote to Production

Rotate your API key to a production key via the developer portal.
Update the base URL to https://api.bluechips.com/v1.
Re-run integration tests using production keys.
Notify the BlueChips trust team to whitelist your production domains for webhook delivery.

REST API Reference

All endpoints require an API key in the Authorization: Bearer header. Requests must be made over HTTPS.

Endpoint	Method	Description
/stamps/create	POST	Registers a new stamp with attestation and consent details.
/stamps/verify/:stamp_id	GET	Validates a stamp and returns provenance signals.
/consent/:stamp_id	GET	Retrieves the notarized consent receipt.
/stamps	GET	Lists stamps filtered by query parameters.

Create a Stamp

POST /stamps/create HTTP/1.1
Host: sandbox.bluechips.com
Authorization: Bearer <API_KEY>
Content-Type: application/json

{
  "file_hash": "b7e23ec29af22b0b4e41da31e868d572...",
  "device_id": "ios-14a8d29a3f",
  "subject_face_hash": "3f29c20d09f...",
  "consent_signed_at": "2025-10-15T14:00:00Z",
  "c2pa_manifest": {
    "claim_generator": "BlueChips/1.0",
    "assertions": [
      {
        "label": "c2pa.actions",
        "data": {
          "actions": [
            {
              "action": "c2pa.created",
              "when": "2025-10-15T14:00:00Z",
              "softwareAgent": "BlueChips Stamps SDK"
            }
          ]
        }
      },
      {
        "label": "c2pa.claim.thumbnail",
        "data": {
          "format": "image/jpeg",
          "identifier": "thumbnail.jpg"
        }
      }
    ],
    "claim_signature": "base64_encoded_signature..."
  },
  "blockchain_options": {
    "network": "permissioned",
    "anchor_to_public": true,
    "public_chain": "ethereum-mainnet",
    "gas_priority": "standard"
  },
  "metadata": {
    "platform": "OnlyFans",
    "creator_id": "user_7238",
    "location": "Los Angeles, CA"
  }
}

Blockchain Options (Optional)

Field	Type	Description
blockchain_options	object	Configuration for blockchain token issuance and anchoring.
blockchain_options.network	string	Target network: "permissioned" (default) or "public" for direct public chain issuance.
blockchain_options.anchor_to_public	boolean	Whether to anchor permissioned ledger state to a public blockchain (default: true).
blockchain_options.public_chain	string	Public chain for anchoring: "ethereum-mainnet", "polygon", "base", or "optimism".
blockchain_options.gas_priority	string	Gas priority for public chain transactions: "low", "standard" (default), or "high".

C2PA Parameters (Optional)

Field	Type	Description
c2pa_manifest	object	C2PA manifest containing claims and assertions about the content.
c2pa_manifest.claim_generator	string	Software that generated the claim (e.g., "BlueChips/1.0").
c2pa_manifest.assertions	array	Array of C2PA assertions (actions, edits, creator info, etc.).
c2pa_manifest.claim_signature	string	Base64-encoded signature of the C2PA claim.

Error Codes

Status	Description
400	Invalid or missing request parameters.
401	Missing or invalid API key.
409	Duplicate stamp for the provided file hash.
422	Failed attestation or consent verification.

Verify a Stamp

GET /stamps/verify/bcstmp_01H93KQZG83FQ2Y4R8J0MCPW7X HTTP/1.1
Host: sandbox.bluechips.com
Authorization: Bearer <API_KEY>

Response:

{
  "stamp_id": "bcstmp_01H93KQZG83FQ2Y4R8J0MCPW7X",
  "valid": true,
  "integrity_score": 0.998,
  "issuer": "BlueChips Trust Authority",
  "issued_at": "2025-10-15T14:00:00Z",
  "device_attestation": {
    "chipset": "Apple A17 Bionic",
    "secure_enclave_verified": true
  },
  "subject_face_match": 0.997,
  "consent_status": "active",
  "blockchain": {
    "token_id": "0x7f3e9a2b1c4d5e6f...",
    "network": "bluechips-permissioned",
    "contract_address": "0x1234567890abcdef...",
    "is_soulbound": true,
    "transferable": false,
    "revocable": true,
    "revoked": false,
    "anchor_tx_hash": "0xdef456...",
    "anchor_chain": "ethereum-mainnet",
    "anchor_verified": true,
    "block_number": 18234567,
    "block_timestamp": "2025-10-15T14:00:23Z"
  },
  "c2pa_validation": {
    "manifest_valid": true,
    "claim_signature_valid": true,
    "trust_chain_valid": true,
    "assertions_verified": 2,
    "content_binding_valid": true
  }
}

Blockchain & Soulbound Tokens

BlueChips Stamps are issued as non-transferable, revocable blockchain tokens (soulbound tokens) that provide tamper-evident proof of identity verification and consent. The system uses a permissioned blockchain for privacy and performance, with optional anchoring to public chains for transparency.

Soulbound Token Properties

Non-transferable: Stamps cannot be transferred to another identity, preventing credential theft or resale.
Revocable: Users or the platform can revoke stamps at any time, immediately invalidating the credential.
Identity-bound: Each stamp is cryptographically bound to the verified user's identity (DID or pseudonymous identifier).
Tamper-evident: Any attempt to modify stamp data breaks the cryptographic chain and invalidates verification.

Architecture

Permissioned Ledger + Public Anchoring

Stamps are minted on a permissioned blockchain (Hyperledger Fabric or Proof-of-Authority Ethereum) for privacy and speed. The ledger state is periodically hashed and anchored to public chains (Ethereum, Polygon, Base, Optimism) for immutable verification. This hybrid approach provides both privacy and transparency.

Network Options

Network	Privacy	Speed	Use Case
permissioned	High	Fast (<1s)	Default for sensitive content platforms (recommended)
public	Lower	Slower (15s-2m)	Maximum transparency for public content verification

Revocation

Stamps can be revoked by the user or platform administrator. Revocation is immediate and propagates to all verifiers within seconds.

POST /stamps/revoke HTTP/1.1
Host: sandbox.bluechips.com
Authorization: Bearer <API_KEY>
Content-Type: application/json

{
  "stamp_id": "bcstmp_01H93KQZG83FQ2Y4R8J0MCPW7X",
  "reason": "user_request",
  "revoked_by": "user_7238"
}

Public Chain Verification

To verify the integrity of a stamp's blockchain record against the public anchor:

GET /stamps/verify-anchor/bcstmp_01H93KQZG83FQ2Y4R8J0MCPW7X HTTP/1.1
Host: sandbox.bluechips.com
Authorization: Bearer <API_KEY>

Response:
{
  "stamp_id": "bcstmp_01H93KQZG83FQ2Y4R8J0MCPW7X",
  "anchor_verified": true,
  "anchor_tx_hash": "0xdef456...",
  "anchor_chain": "ethereum-mainnet",
  "block_number": 18234567,
  "merkle_proof": ["0xabc...", "0xdef...", "0x123..."],
  "root_hash": "0x789..."
}

JavaScript & TypeScript SDK

Install the official package from npm:

npm install @bluechips/stamps

Initialization

import { BlueChips } from "@bluechips/stamps";

type Env = "sandbox" | "production";

const client = new BlueChips({
  apiKey: process.env.BLUECHIPS_KEY!,
  environment: (process.env.BLUECHIPS_ENV as Env) ?? "sandbox",
});

Creating a Stamp

import { promises as fs } from "node:fs";

async function createStamp() {
  const fileBytes = await fs.readFile("./video.mp4");
  const subjectFace = await fs.readFile("./face.jpg");

  const stamp = await client.createStamp({
    fileBytes,
    subjectFace,
    deviceId: "ios-14a8d29a3f",
    consentSignedAt: new Date().toISOString(),
    c2paManifest: {
      claimGenerator: "BlueChips/1.0",
      assertions: [
        {
          label: "c2pa.actions",
          data: {
            actions: [
              {
                action: "c2pa.created",
                when: new Date().toISOString(),
                softwareAgent: "BlueChips Stamps SDK"
              }
            ]
          }
        }
      ]
    },
    blockchainOptions: {
      network: "permissioned",
      anchorToPublic: true,
      publicChain: "ethereum-mainnet",
      gasPriority: "standard"
    },
    metadata: {
      platform: "OnlyFans",
      creator_id: "user_7238",
      location: "Los Angeles, CA",
    },
  });

  console.log("Stamp created", stamp.id);
  console.log("Soulbound token:", stamp.blockchain.tokenId);
  console.log("Is transferable:", stamp.blockchain.transferable); // false
  if (stamp.c2paValidation?.manifestValid) {
    console.log("C2PA manifest validated successfully");
  }
}

Verifying a Stamp

async function verifyStamp(stampId: string) {
  const verification = await client.verifyStamp(stampId);

  if (!verification.valid) {
    throw new Error(`Stamp ${stampId} failed verification`);
  }

  console.log("Face match score", verification.subject_face_match);
}

Python SDK

Install the package from PyPI:

pip install bluechips-stamps

Initialization

from bluechips_stamps import BlueChips

client = BlueChips(api_key="${BLUECHIPS_KEY}", environment="sandbox")

Creating a Stamp

from datetime import datetime

stamp = client.create_stamp(
    file_path="./video.mp4",
    subject_face_path="./face.jpg",
    device_id="ios-14a8d29a3f",
    consent_signed_at=datetime.utcnow().isoformat() + "Z",
    c2pa_manifest={
        "claim_generator": "BlueChips/1.0",
        "assertions": [
            {
                "label": "c2pa.actions",
                "data": {
                    "actions": [
                        {
                            "action": "c2pa.created",
                            "when": datetime.utcnow().isoformat() + "Z",
                            "softwareAgent": "BlueChips Stamps SDK"
                        }
                    ]
                }
            }
        ]
    },
    blockchain_options={
        "network": "permissioned",
        "anchor_to_public": True,
        "public_chain": "ethereum-mainnet",
        "gas_priority": "standard"
    },
    metadata={
        "platform": "OnlyFans",
        "creator_id": "user_7238",
        "location": "Los Angeles, CA",
    },
)

print("Stamp created", stamp["stamp_id"])
print("Soulbound token:", stamp["blockchain"]["token_id"])
print("Is transferable:", stamp["blockchain"]["transferable"])  # False
if stamp.get("c2pa_validation", {}).get("manifest_valid"):
    print("C2PA manifest validated successfully")

CLI Utilities

The BlueChips CLI streamlines integration tasks for developers and trust teams.

Installation

curl -sSL https://cli.bluechips.com/install.sh | bash

Commands

Command	Description
bluechips stamps create	Register a new stamp from local files.
bluechips stamps verify	Verify a stamp and print a summary.
bluechips consent get	Download a consent receipt as PDF or JSON.
bluechips webhook tunnel	Open a secure tunnel for webhook delivery.

Webhooks

Webhooks notify platforms of key lifecycle events for stamps and consent receipts.

Events

Event	Description
stamp.created	Fired when a new stamp is registered.
stamp.verified	Triggered when verification succeeds.
consent.revoked	Fired when the creator revokes consent.

Payload Structure

{
  "event": "stamp.verified",
  "stamp_id": "bcstmp_01H93KQZG83FQ2Y4R8J0MCPW7X",
  "verified_at": "2025-10-15T14:20:00Z"
}

Security

BlueChips signs requests with an HMAC-SHA256 signature using your webhook secret.
Validate the X-BlueChips-Signature header by recomputing the signature over the request body.
Reject requests older than five minutes to mitigate replay attacks.
Enforce HTTPS with valid TLS certificates.

Security & Compliance

BlueChips Stamps is designed for sensitive content workflows that demand verifiable authenticity and consent guarantees.

Zero-Knowledge Consent Proofs

Consent receipts are hashed with zk-SNARK compatible circuits.
Receipts disclose only necessary metadata while preserving subject privacy.
Revocation events update the proof to invalidate prior consent tokens.

Hardware Root of Trust

Supported secure enclaves:

Apple Secure Enclave (A15 and newer)
Android StrongBox / Titan M2
Windows TPM 2.0

Data Protection

All data is encrypted in transit (TLS 1.3) and at rest (AES-256 GCM).
API keys are scoped and rotated every 90 days.
Consent receipts may be deleted or revoked on demand to comply with GDPR & CCPA.

Compliance Certifications

SOC 2 Type II
ISO/IEC 27001
GDPR & CCPA compliant data handling

Responsible Disclosure

Report security vulnerabilities to rick@bluechips.com

Support Channels

Email: rick@bluechips.com
Status Page: status.bluechips.com