Deep Composition API

RESTful API endpoints for identity verification, compliance checking, and data integrity validation using the Deep Composition Engine.

Base URL

https://api.zkpret.org/v1

Authentication

All API requests require authentication using API keys:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Identity Verification

Validate Legal Entity

POST/api/identity/validate-entity

Validate legal entity identification and credentials using LEI and enhanced KYC data.

Request Body:

{
  "entityType": "LEGAL_ENTITY",
  "leiCode": "5493001KJTIIGC8Y1R12",
  "credentials": {
    "businessLicense": "encrypted_license_data",
    "corporateStructure": "encrypted_structure_data",
    "beneficialOwnership": "encrypted_ownership_data"
  },
  "jurisdiction": ["US", "EU"],
  "complianceLevel": "INSTITUTIONAL"
}

Response:

{
  "success": true,
  "data": {
    "proofId": "proof_entity_abc123",
    "entityHash": "0x1a2b3c4d...",
    "validationStatus": "VALID",
    "complianceScore": 0.95,
    "validUntil": "2024-12-31T23:59:59Z",
    "verificationMethods": ["LEI_REGISTRY", "KYC_ENHANCED", "CORPORATE_VERIFICATION"]
  },
  "metadata": {
    "processingTime": "2.3s",
    "standardsUsed": ["LEI", "FATF_GUIDELINES"],
    "jurisdictions": ["US", "EU"]
  }
}

Get LEI Information

GET/api/identity/lei/{leiCode}

Retrieve Legal Entity Identifier information without exposing sensitive business details.

Parameters:

leiCode (string, required): Valid LEI code (20 characters)

Response:

{
  "success": true,
  "data": {
    "leiCode": "5493001KJTIIGC8Y1R12",
    "entityStatus": "ACTIVE",
    "registrationStatus": "ISSUED",
    "validationSources": ["LEI_REGISTRY", "SWIFT_NETWORK"],
    "lastUpdated": "2024-01-15T10:30:00Z",
    "jurisdictionOfIncorporation": "US-DE",
    "entityCategory": "GENERAL",
    "proofAvailable": true
  }
}

Error Handling

All API responses follow a consistent error format:

{
  "success": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Document validation failed: Invalid DCSA format",
    "details": {
      "validationErrors": [
        {
          "field": "transportDocumentReference",
          "error": "REQUIRED_FIELD_MISSING",
          "description": "Transport document reference is required for DCSA compliance"
        }
      ],
      "suggestedActions": [
        "Ensure all required DCSA fields are present",
        "Validate document format before submission"
      ]
    },
    "requestId": "req_abc123def456",
    "timestamp": "2024-02-20T14:30:00Z"
  }
}

Common Error Codes

Code	Description	HTTP Status
`INVALID_API_KEY`	API key is invalid or expired	401
`INSUFFICIENT_PERMISSIONS`	API key lacks required permissions	403
`VALIDATION_FAILED`	Document or data validation failed	400
`COMPLIANCE_CHECK_FAILED`	Compliance validation failed	400
`PROOF_GENERATION_FAILED`	Unable to generate proof	500
`PROOF_NOT_FOUND`	Requested proof does not exist	404
`RATE_LIMIT_EXCEEDED`	API rate limit exceeded	429
`JURISDICTION_NOT_SUPPORTED`	Requested jurisdiction not supported	400
`STANDARD_NOT_SUPPORTED`	Requested standard not supported	400
`NETWORK_ERROR`	Blockchain network connectivity issue	503

Rate Limits

API endpoints have the following rate limits:

Endpoint Category	Rate Limit	Burst Limit
Identity Validation	100 requests/hour	10 requests/minute
Compliance Checking	200 requests/hour	20 requests/minute
Document Validation	500 requests/hour	50 requests/minute
Proof Composition	50 requests/hour	5 requests/minute
Proof Verification	1000 requests/hour	100 requests/minute

Rate limit headers are included in all responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200
X-Retry-After: 3600

SDKs and Libraries

TypeScript/JavaScript

npm install @zkpret/sdk

import { ZKPRETClient } from '@zkpret/sdk';

const client = new ZKPRETClient({
  apiKey: 'your_api_key',
  environment: 'production' // or 'sandbox'
});

// Validate entity
const entityProof = await client.identity.validateEntity({
  entityType: 'LEGAL_ENTITY',
  leiCode: '5493001KJTIIGC8Y1R12',
  credentials: encryptedCredentials,
  jurisdiction: ['US', 'EU']
});

// Compose proof
const composedProof = await client.proofs.compose({
  proofComponents: [entityProof, documentProof, complianceProof],
  compositionLevel: 'LEVEL_3',
  businessLogic: {
    useCase: 'SUPPLY_CHAIN_FINANCE',
    riskThreshold: 0.05
  }
});

Python

pip install zkpret-python

from zkpret import ZKPRETClient

client = ZKPRETClient(
    api_key='your_api_key',
    environment='production'
)

# Validate document
document_proof = client.data.validate_document(
    document_type='BILL_OF_LADING',
    standard='DCSA_v3',
    document={
        'document_hash': '0x9f86d081...',
        'encrypted_content': encrypted_content,
        'metadata': metadata
    }
)

# Verify proof
verification = client.proofs.verify(document_proof.proof_id)
print(f"Proof valid: {verification.is_valid}")

Java

<dependency>
    <groupId>org.zkpret</groupId>
    <artifactId>zkpret-java-sdk</artifactId>
    <version>2.1.0</version>
</dependency>

import org.zkpret.ZKPRETClient;
import org.zkpret.models.*;

ZKPRETClient client = new ZKPRETClient.Builder()
    .apiKey("your_api_key")
    .environment(Environment.PRODUCTION)
    .build();

// Validate compliance
ComplianceValidationRequest request = ComplianceValidationRequest.builder()
    .entityProof("proof_entity_abc123")
    .regulations(Arrays.asList(
        new Regulation("EU", Arrays.asList("GDPR", "AML5_DIRECTIVE")),
        new Regulation("US", Arrays.asList("SOX", "FCPA"))
    ))
    .validationLevel(ValidationLevel.ENHANCED)
    .build();

ComplianceProof proof = client.compliance().validate(request);
System.out.println("Compliance status: " + proof.getOverallStatus());

Webhooks

Subscribe to real-time updates on proof status and validation results:

Webhook Configuration

POST/api/webhooks/configure

{
  "url": "https://your-domain.com/webhooks/zkpret",
  "events": [
    "proof.generated",
    "proof.verified", 
    "proof.expired",
    "validation.completed",
    "compliance.updated"
  ],
  "secret": "your_webhook_secret"
}

Webhook Payload Example

{
  "event": "proof.generated",
  "timestamp": "2024-02-20T14:30:00Z",
  "data": {
    "proofId": "proof_composed_mno345",
    "proofType": "COMPOSED_PROOF_LEVEL_3",
    "status": "GENERATED",
    "useCase": "SUPPLY_CHAIN_FINANCE",
    "validUntil": "2024-12-31T23:59:59Z"
  },
  "signature": "sha256=abc123def456..."
}

Testing and Development

Sandbox Environment

Use the sandbox environment for testing:

https://sandbox-api.zkpret.org/v1

Sandbox features:

No rate limits
Mock data responses
Test API keys
Sample documents and entities
Proof verification without blockchain costs

Test Data

Sample test entities and documents are available:

{
  "testEntities": {
    "msme_exporter": "lei_test_001",
    "large_importer": "lei_test_002",
    "financial_institution": "lei_test_003"
  },
  "testDocuments": {
    "bill_of_lading": "doc_test_bol_001",
    "commercial_invoice": "doc_test_inv_001", 
    "purchase_order": "doc_test_po_001"
  },
  "testProofs": {
    "entity_proof": "proof_test_entity_001",
    "document_proof": "proof_test_doc_001",
    "composed_proof": "proof_test_composed_001"
  }
}

Support and Resources

API Status: status.zkpret.org
Developer Forum: forum.zkpret.org
GitHub Repository: github.com/zkpret/zkpret-sdk
Postman Collection: Available on Postman
OpenAPI Specification: swagger.zkpret.org

Changelog

v2.1.0 (Current)

Added recursive proof composition
Enhanced compliance validation
Improved performance for document validation
Added support for DCSA v3.0
Expanded jurisdiction coverage

v2.0.0

Major rewrite with improved privacy features
MINA blockchain integration
Multi-level proof composition
Enhanced error handling

v1.0.0

Initial API release
Basic document validation
Entity verification
Simple compliance checking

Deep Composition API

Base URL​

Authentication​

Identity Verification​

Validate Legal Entity​

Get LEI Information​

Error Handling​

Common Error Codes​

Rate Limits​

SDKs and Libraries​

TypeScript/JavaScript​

Python​

Java​

Webhooks​

Webhook Configuration​

Webhook Payload Example​

Testing and Development​

Sandbox Environment​

Test Data​

Support and Resources​

Changelog​

v2.1.0 (Current)​

v2.0.0​

v1.0.0​