Auction House Integration

This guide covers integrating Optropic for auction houses and high-value collectibles. You'll learn to register objects, track provenance, manage ownership transfers, and provide verification to buyers.

Use Cases

Luxury Watches — Authenticate Rolex, Patek Philippe, etc.
Fine Art — Track painting provenance from gallery to collector
Wine & Spirits — Verify premium bottles
Collectibles — Trading cards, memorabilia, limited editions

API Endpoints for Auction

Endpoint	Description
`POST /auction/objects/register`	Register a new auction object
`GET /auction/public/verify/:serial`	Public verification (QR landing)
`GET /auction/objects/:serial/provenance`	Full provenance history
`POST /auction/transfers/initiate`	Start ownership transfer

Step 1: Register an Object

When a consignor brings an item for auction:

curl -X POST https://api.optropic.com/api/v1/auction/objects/register \
  -H "x-api-key: optr_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Rolex Cosmograph Daytona Ref. 116500LN",
    "category": "watch",
    "description": "2023, Box and Papers, Excellent Condition",
    "estimated_value": {
      "min": 25000,
      "max": 35000,
      "currency": "EUR"
    }
  }'

Response:

{
  "object": {
    "id": "obj_abc123",
    "optropic_serial": "AUC-20260218-DAYT0001",
    "title": "Rolex Cosmograph Daytona Ref. 116500LN",
    "category": "watch",
    "status": "consigned",
    "security_tier": "enhanced",
    "anchor_count": 11,
    "entropy_bits": 1650
  },
  "qr_data": {
    "gs1DigitalLink": "https://id.optropic.com/01/0000000000001/21/AUC-20260218-DAYT0001/10/watch?sig=...",
    "serial": "AUC-20260218-DAYT0001"
  }
}

Step 2: Photograph and Bind

Upload reference photos to create a cryptographic binding:

async function uploadPhotos(objectId, photos) {
  for (const photo of photos) {
    const formData = new FormData();
    formData.append('photo', photo.file);
    formData.append('angle', photo.angle); // 'dial', 'caseback', 'movement', etc.

    await fetch(`https://api.optropic.com/api/v1/auction/objects/${objectId}/photos`, {
      method: 'POST',
      headers: { 'x-api-key': process.env.OPTROPIC_API_KEY },
      body: formData,
    });
  }
}

// Required angles per category
const requiredAngles = {
  watch: ['dial', 'movement', 'serial_engraving', 'case_back'],
  painting: ['overall', 'detail_1', 'detail_2', 'signature', 'reverse'],
  bottle: ['front_label', 'closure', 'back_label', 'fill_level'],
};

Step 3: Create Provenance Events

Track the object's journey through your auction house:

// When item is cataloged
await createProvenanceEvent({
  objectId: 'obj_abc123',
  eventType: 'cataloged',
  actorRole: 'auction_house',
  description: 'Item cataloged for Spring 2026 auction',
  evidence: {
    catalogNumber: 'LOT-2026-S-0042',
    condition: 'Excellent',
  },
});

// When item is listed
await createProvenanceEvent({
  objectId: 'obj_abc123',
  eventType: 'listed',
  actorRole: 'auction_house',
  description: 'Listed in Spring Luxury Watch Auction',
  evidence: {
    auctionId: 'AUC-2026-SPRING',
    lotNumber: 42,
    estimateLow: 25000,
    estimateHigh: 35000,
  },
});

Step 4: Public Verification

When a potential buyer scans the QR code, they hit the public verification endpoint:

curl https://api.optropic.com/api/v1/auction/public/verify/AUC-20260218-DAYT0001

Response (no auth required):

{
  "status": "authentic",
  "confidence": 0.95,
  "object": {
    "title": "Rolex Cosmograph Daytona Ref. 116500LN",
    "category": "watch",
    "serial": "AUC-20260218-DAYT0001",
    "security_tier": "enhanced",
    "registered_at": "2026-02-18T10:00:00Z"
  },
  "cryptographic_identity": {
    "signature_valid": true,
    "photo_binding": "valid",
    "tag_status": "verified"
  },
  "provenance": {
    "event_count": 3,
    "chain_intact": true,
    "current_owner": "Verified Private Collector",
    "latest_event": "listed"
  },
  "security": {
    "spatial_relations": 55,
    "entropy_bits": 1650,
    "tier_label": "Reference Grade"
  }
}

Privacy by Design

The public endpoint never exposes owner names, emails, or internal IDs. Owners are shown as "Verified Private Collector" only.

Step 5: Ownership Transfer

When the auction concludes and payment is confirmed:

// Initiate transfer
const transfer = await fetch('https://api.optropic.com/api/v1/auction/transfers/initiate', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.OPTROPIC_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    objectId: 'obj_abc123',
    fromOwnerId: 'owner_seller',
    toOwnerId: 'owner_buyer',
    salePrice: 28500,
    saleCurrency: 'EUR',
  }),
});

// Returns a 6-digit transfer code
const { transferCode, expiresAt } = await transfer.json();
// Give transferCode to buyer to confirm receipt

The buyer confirms receipt:

await fetch(`https://api.optropic.com/api/v1/auction/transfers/${transferId}/confirm`, {
  method: 'POST',
  headers: {
    'x-api-key': process.env.OPTROPIC_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    transferCode: '847291', // Code provided to buyer
  }),
});

Full Provenance History

Get complete chain of custody:

curl https://api.optropic.com/api/v1/auction/objects/AUC-20260218-DAYT0001/provenance

{
  "object": {
    "serial": "AUC-20260218-DAYT0001",
    "title": "Rolex Cosmograph Daytona Ref. 116500LN"
  },
  "chain_valid": true,
  "events": [
    {
      "type": "registered",
      "timestamp": "2026-02-18T10:00:00Z",
      "actor": { "type": "auction_house", "name": "Christie's Geneva" }
    },
    {
      "type": "cataloged",
      "timestamp": "2026-02-20T14:30:00Z",
      "details": { "catalogNumber": "LOT-2026-S-0042" }
    },
    {
      "type": "listed",
      "timestamp": "2026-03-01T09:00:00Z",
      "details": { "lotNumber": 42 }
    },
    {
      "type": "sold",
      "timestamp": "2026-03-15T15:42:00Z",
      "details": { "hammerPrice": 28500, "currency": "EUR" }
    }
  ],
  "chain_of_custody": [
    { "from": null, "to": "Consignor", "transfer_type": "registration" },
    { "from": "Consignor", "to": "Buyer", "transfer_type": "sale" }
  ]
}

Dashboard Integration

Build a dashboard showing your auction objects:

async function loadDashboard() {
  const response = await fetch(
    'https://api.optropic.com/api/v1/auction/dashboard/objects?status=listed&limit=20',
    {
      headers: { 'x-api-key': process.env.OPTROPIC_API_KEY },
    }
  );

  const { objects, pagination } = await response.json();

  objects.forEach(obj => {
    console.log(`${obj.serial}: ${obj.title}`);
    console.log(`  Status: ${obj.status}`);
    console.log(`  Photos: ${obj.photo_status.count}/${obj.photo_status.required}`);
    console.log(`  Binding: ${obj.photo_status.binding_status}`);
  });
}

Security Considerations

Never expose owner PII in public endpoints
Require photo binding before listing
Monitor scan patterns for suspicious activity
Use transfer codes for ownership changes
Maintain hash chain for provenance integrity

Use Cases​

API Endpoints for Auction​

Step 1: Register an Object​

Step 2: Photograph and Bind​

Step 3: Create Provenance Events​

Step 4: Public Verification​

Step 5: Ownership Transfer​

Full Provenance History​

Dashboard Integration​

Security Considerations​