# PACT Entity CLI - API Reference This document provides comprehensive API reference for PACT Entity CLI commands, including detailed parameter specifications, response formats, and integration examples. ## Table of Contents - [Command Interface](#command-interface) - [Global Options](#global-options) - [Commands](#commands) - [create](#create) - [update](#update) - [timeline](#timeline) - [score](#score) - [link](#link) - [export](#export) - [search](#search) - [status](#status) - [fuse](#fuse) - [Data Models](#data-models) - [Response Formats](#response-formats) - [Error Handling](#error-handling) - [Integration Examples](#integration-examples) ## Command Interface All PACT Entity CLI commands follow a consistent interface pattern: ```bash pact-entity [options] [--global-options] ``` ### Exit Codes - `0`: Success - `1`: General error - `2`: Configuration error - `3`: Network error - `4`: Validation error ## Global Options These options are available for all commands: | Option | Type | Description | Default | |--------|------|-------------|---------| | `--config ` | string | Path to configuration file | `~/.pactrc` | | `--verbose` | boolean | Enable verbose output | false | | `--no-banner` | boolean | Disable startup banner | false | | `--json` | boolean | Output results in JSON format | false | | `--proof` | boolean | Generate cryptographic proof | false | | `--debug` | boolean | Enable debug mode | false | | `--help` | boolean | Show command help | false | | `--version` | boolean | Show version information | false | ## Commands ### create Creates a new entity compliance profile. #### Syntax ```bash pact-entity create [options] ``` #### Options | Option | Type | Required | Description | Default | |--------|------|----------|-------------|---------| | `--type ` | string | No | Entity type (individual, organization, wallet) | 'individual' | | `--name ` | string | No | Entity name or identifier | - | | `--metadata ` | string | No | Additional metadata as JSON | {} | | `--interactive` | boolean | No | Interactive profile creation | false | #### Response Format **Standard Output:** ``` ✓ Entity created successfully ID: entity-a1b2c3d4 Type: individual Name: Alice Smith Compliance Score: 0.50 Created: 2024-08-01T12:00:00Z ``` **JSON Output (`--json`):** ```json { "success": true, "entity": { "id": "entity-a1b2c3d4", "type": "individual", "name": "Alice Smith", "complianceScore": 0.5, "kycStatus": "pending", "amlStatus": "pending", "riskScore": 0.5, "metadata": {}, "created": "2024-08-01T12:00:00Z" }, "proof": "pact-proof-a1b2c3d4e5f6g7h8" } ``` #### Examples ```bash # Basic entity creation pact-entity create --type individual --name "Alice Smith" # Organization with metadata pact-entity create --type organization --name "Acme Corp" --metadata '{"industry":"fintech","employees":100}' # Interactive creation pact-entity create --interactive # JSON output with proof pact-entity create --name "Bob Jones" --json --proof ``` ### update Updates existing entity profile information. #### Syntax ```bash pact-entity update --entity [options] ``` #### Options | Option | Type | Required | Description | Default | |--------|------|----------|-------------|---------| | `--entity ` | string | Yes | Entity identifier | - | | `--kyc ` | string | No | KYC status (pending, verified, rejected) | - | | `--aml ` | string | No | AML status (pending, completed, failed) | - | | `--risk ` | number | No | Risk score (0.0-1.0) | - | | `--metadata ` | string | No | Updated metadata as JSON | - | #### Response Format **Standard Output:** ``` ✓ Entity updated successfully ID: alice.eth Changes: KYC Status: pending → verified Risk Score: 0.50 → 0.20 Updated: 2024-08-01T12:30:00Z ``` **JSON Output (`--json`):** ```json { "success": true, "entity": { "id": "alice.eth", "changes": { "kycStatus": { "before": "pending", "after": "verified" }, "riskScore": { "before": 0.5, "after": 0.2 } }, "updated": "2024-08-01T12:30:00Z" }, "proof": "pact-proof-b2c3d4e5f6g7h8i9" } ``` #### Examples ```bash # Update KYC status pact-entity update --entity alice.eth --kyc verified # Update multiple fields pact-entity update --entity alice.eth --kyc verified --aml completed --risk 0.15 # Update metadata pact-entity update --entity alice.eth --metadata '{"verified_date":"2024-08-01"}' ``` ### timeline Views compliance timeline and event history for an entity. #### Syntax ```bash pact-entity timeline --entity [options] ``` #### Options | Option | Type | Required | Description | Default | |--------|------|----------|-------------|---------| | `--entity ` | string | Yes | Entity identifier | - | | `--limit ` | number | No | Number of events to show | 20 | | `--filter ` | string | No | Filter by event type | - | | `--export` | boolean | No | Export timeline data | false | #### Response Format **Standard Output:** ``` Timeline for alice.eth (last 5 events): 2024-08-01 12:30:00 KYC_VERIFIED ✓ KYC verification completed 2024-08-01 11:15:00 AML_COMPLETED ✓ AML screening passed 2024-08-01 10:00:00 TRANSACTION → High-value transaction: $50,000 2024-07-31 14:20:00 RISK_UPDATED ⚠ Risk score changed: 0.5 → 0.3 2024-07-30 09:00:00 ENTITY_CREATED 🆕 Entity profile created ``` **JSON Output (`--json`):** ```json { "success": true, "entity": "alice.eth", "timeline": [ { "timestamp": "2024-08-01T12:30:00Z", "type": "KYC_VERIFIED", "description": "KYC verification completed", "metadata": { "verificationProvider": "jumio", "score": 0.95 } }, { "timestamp": "2024-08-01T11:15:00Z", "type": "AML_COMPLETED", "description": "AML screening passed", "metadata": { "provider": "chainalysis", "riskLevel": "low" } } ], "totalEvents": 25, "shown": 5 } ``` #### Examples ```bash # View recent timeline pact-entity timeline --entity alice.eth # Filter by event type pact-entity timeline --entity alice.eth --filter kyc --limit 5 # Export timeline data pact-entity timeline --entity alice.eth --export --json > alice-timeline.json ``` ### score Calculates and displays compliance scores with detailed breakdowns. #### Syntax ```bash pact-entity score --entity [options] ``` #### Options | Option | Type | Required | Description | Default | |--------|------|----------|-------------|---------| | `--entity ` | string | Yes | Entity identifier | - | | `--detailed` | boolean | No | Show detailed score breakdown | false | | `--compare ` | string | No | Compare multiple entities (comma-separated) | - | #### Response Format **Standard Output:** ``` Compliance Score for alice.eth Overall Score: 82/100 (Excellent) ↗ +5% this month Component Breakdown: KYC Compliance [████████░░] 85/100 (30% weight) AML Compliance [█████████░] 90/100 (30% weight) Transaction Score [███████░░░] 75/100 (20% weight) Behavior Score [████████░░] 80/100 (20% weight) Risk Assessment: LOW Trend: IMPROVING Last Updated: 2024-08-01T12:30:00Z ``` **JSON Output (`--json`):** ```json { "success": true, "entity": "alice.eth", "score": { "overall": 82, "components": { "kyc": { "score": 85, "weight": 0.3, "status": "verified" }, "aml": { "score": 90, "weight": 0.3, "status": "completed" }, "transaction": { "score": 75, "weight": 0.2, "status": "monitoring" }, "behavior": { "score": 80, "weight": 0.2, "status": "normal" } }, "riskLevel": "low", "trend": "improving", "lastUpdated": "2024-08-01T12:30:00Z" } } ``` #### Examples ```bash # Basic score display pact-entity score --entity alice.eth # Detailed breakdown pact-entity score --entity alice.eth --detailed # Compare entities pact-entity score --entity alice.eth --compare bob.eth,charlie.eth ``` ### link Creates and manages relationships between entities. #### Syntax ```bash pact-entity link --from --to [options] ``` #### Options | Option | Type | Required | Description | Default | |--------|------|----------|-------------|---------| | `--from ` | string | Yes | Source entity identifier | - | | `--to ` | string | Yes | Target entity identifier | - | | `--type ` | string | No | Relationship type | 'associated' | | `--metadata ` | string | No | Relationship metadata | {} | #### Relationship Types - `associated`: General association - `employee`: Employment relationship - `owns`: Ownership relationship - `partner`: Partnership relationship - `subsidiary`: Corporate hierarchy - `vendor`: Business relationship - `family`: Family relationship - `controls`: Control relationship #### Response Format **Standard Output:** ``` ✓ Relationship created successfully From: alice.eth To: acme-corp Type: employee Relationship ID: rel-x1y2z3a4 Created: 2024-08-01T13:00:00Z ``` **JSON Output (`--json`):** ```json { "success": true, "relationship": { "id": "rel-x1y2z3a4", "from": "alice.eth", "to": "acme-corp", "type": "employee", "metadata": { "startDate": "2024-01-01", "department": "engineering" }, "status": "active", "created": "2024-08-01T13:00:00Z" }, "proof": "pact-proof-c3d4e5f6g7h8i9j0" } ``` #### Examples ```bash # Basic relationship pact-entity link --from alice.eth --to acme-corp --type employee # With metadata pact-entity link --from alice.eth --to wallet123 --type owns --metadata '{"since":"2024-01-01","verified":true}' # Partnership pact-entity link --from company-a --to company-b --type partner ``` ### export Exports entity profile data in multiple formats. #### Syntax ```bash pact-entity export --entity [options] ``` #### Options | Option | Type | Required | Description | Default | |--------|------|----------|-------------|---------| | `--entity ` | string | Yes | Entity identifier or "all" | - | | `--format ` | string | No | Export format (json, csv, pdf) | 'json' | | `--output ` | string | No | Output file path | auto-generated | | `--include ` | string | No | Fields to include (comma-separated) | all | #### Export Formats **JSON Format:** - Complete entity data with nested objects - Includes relationships and timeline events - Machine-readable format **CSV Format:** - Flattened entity data - Suitable for spreadsheet analysis - Relationship data in separate columns **PDF Format:** - Human-readable compliance report - Includes charts and visualizations - Professional formatting #### Response Format **Standard Output:** ``` ✓ Export completed successfully Entity: alice.eth Format: JSON File: alice-eth-export-20240801.json Size: 2.4 KB Records: 1 entity, 5 relationships, 25 timeline events ``` **JSON Output (`--json`):** ```json { "success": true, "export": { "entity": "alice.eth", "format": "json", "filePath": "./alice-eth-export-20240801.json", "fileSize": "2.4 KB", "recordCount": { "entities": 1, "relationships": 5, "timelineEvents": 25 }, "timestamp": "2024-08-01T13:30:00Z" } } ``` #### Examples ```bash # Export single entity as JSON pact-entity export --entity alice.eth # Export as CSV pact-entity export --entity alice.eth --format csv --output alice.csv # Bulk export all entities pact-entity export --entity all --format json # Export specific fields only pact-entity export --entity alice.eth --include "id,name,complianceScore,kycStatus" ``` ### search Searches and filters entities based on various criteria. #### Syntax ```bash pact-entity search [options] ``` #### Options | Option | Type | Required | Description | Default | |--------|------|----------|-------------|---------| | `--type ` | string | No | Filter by entity type | - | | `--status ` | string | No | Filter by compliance status | - | | `--score ` | string | No | Filter by score with operators | - | | `--limit ` | number | No | Limit search results | 10 | #### Score Expressions Support for comparison operators: - `>0.8`: Greater than 0.8 - `>=0.7`: Greater than or equal to 0.7 - `<0.5`: Less than 0.5 - `<=0.3`: Less than or equal to 0.3 - `=0.9`: Exactly equal to 0.9 #### Response Format **Standard Output:** ``` Search Results (3 entities found): ID: alice.eth Type: individual Score: 82/100 ✓ verified Name: Alice Smith Risk: LOW Updated: 2h ago ID: bob.eth Type: individual Score: 75/100 ⚠ pending Name: Bob Jones Risk: MEDIUM Updated: 1d ago ID: acme-corp Type: organization Score: 90/100 ✓ verified Name: Acme Corp Risk: LOW Updated: 3h ago ``` **JSON Output (`--json`):** ```json { "success": true, "results": [ { "id": "alice.eth", "type": "individual", "name": "Alice Smith", "complianceScore": 82, "kycStatus": "verified", "amlStatus": "completed", "riskLevel": "low", "lastUpdated": "2024-08-01T11:30:00Z" } ], "totalFound": 3, "showing": 3, "filters": { "type": "individual", "scoreExpression": ">0.7" } } ``` #### Examples ```bash # Search by type pact-entity search --type organization # Search by score range pact-entity search --score ">0.8" --limit 20 # Complex search pact-entity search --type individual --status verified --score ">=0.7" ``` ### status Displays entity-specific or system-wide status information. #### Syntax ```bash pact-entity status [options] ``` #### Options | Option | Type | Required | Description | Default | |--------|------|----------|-------------|---------| | `--entity ` | string | No | Show status for specific entity | - | | `--summary` | boolean | No | Show system-wide summary | false | #### Response Format **Entity Status:** ``` Status for alice.eth Profile Information: Type: individual Name: Alice Smith Created: 2024-07-30T09:00:00Z Last Updated: 2024-08-01T12:30:00Z Compliance Status: Overall Score: 82/100 (Excellent) KYC Status: ✓ verified AML Status: ✓ completed Risk Level: LOW Relationships: 3 active connections → acme-corp (employee) → wallet123 (owns) → family-trust (beneficiary) Recent Activity: • KYC verification completed (2h ago) • Risk score updated (1d ago) • New relationship added (3d ago) ``` **System Summary:** ``` PACT Entity System Status Total Entities: 1,247 Individual: 856 (68.6%) Organization: 312 (25.0%) Wallet: 79 (6.3%) Compliance Distribution: Excellent (80-100): 423 entities (33.9%) Good (60-79): 612 entities (49.1%) Fair (40-59): 187 entities (15.0%) Poor (0-39): 25 entities (2.0%) Average Compliance Score: 74.2/100 System Health: ✓ Operational Last Updated: 2024-08-01T13:45:00Z ``` #### Examples ```bash # Entity-specific status pact-entity status --entity alice.eth # System summary pact-entity status --summary # JSON system status pact-entity status --summary --json ``` ### fuse Advanced compliance vector analysis with AI-powered insights and entity relationship detection. #### Syntax ```bash pact-entity fuse --entity [options] ``` #### Options | Option | Type | Required | Description | Default | |--------|------|----------|-------------|---------| | `--entity ` | string | Yes | Entity identifier | - | | `--export ` | string | No | Export vector to file | - | | `--graph [format]` | string | No | Generate/export graph (dot, json) | - | | `--summary` | boolean | No | Display vector summary | false | | `--skip-linking` | boolean | No | Skip entity relationship detection | false | | `--ai-summary` | boolean | No | Generate AI-powered analysis | false | #### Vector Dimensions The compliance vector consists of 8 dimensions: 1. **kyc_score**: Identity verification completeness (0-1) 2. **avg_risk**: Inverted average risk score (0-1) 3. **sanctions_flag**: Sanctions clearance status (0-1) 4. **qr_events**: QR verification activity frequency (0-1) 5. **high_value_tx**: High-value transaction ratio (inverted, 0-1) 6. **contract_exposure**: Smart contract interaction level (0-1) 7. **token_diversity**: Token portfolio diversity (0-1) 8. **anomaly_frequency**: Behavioral anomaly frequency (inverted, 0-1) #### Response Format **Vector Summary:** ``` Compliance Vector for alice.eth Vector Components: KYC Score: 0.95 ████████████████████▌ Risk Score: 0.80 ████████████████░░░░░ Sanctions: 1.00 █████████████████████ QR Events: 0.65 █████████████░░░░░░░░ High Value TX: 0.75 ███████████████░░░░░░ Contract Exp: 0.40 ████████░░░░░░░░░░░░░ Token Div: 0.85 █████████████████░░░░ Anomalies: 0.90 ██████████████████░░░ Vector Magnitude: 0.789 Checksum: sha256:a1b2c3d4... Related Entities Found: 3 → bob.eth (similarity: 0.87) → charlie.eth (similarity: 0.82) → delta-corp (similarity: 0.79) ``` **AI Analysis Example:** ``` AI Compliance Analysis for alice.eth 🎯 Risk Assessment: LOW (Score: 82/100) ✅ Strengths: • Excellent KYC verification (95% complete) • Clean sanctions screening record • Diverse token portfolio indicating legitimate activity • Low anomaly frequency suggests consistent behavior ⚠️ Areas for Improvement: • Limited smart contract interactions may indicate reduced DeFi engagement • QR verification activity could be increased for better compliance tracking 🔍 Behavioral Insights: • Transaction patterns indicate institutional-grade compliance • Risk profile aligns with verified individual status • No suspicious activity flags detected 📊 Regulatory Compliance: • Meets EU GDPR requirements • Compliant with US AML/KYC standards • Suitable for institutional partnerships 🎯 Recommendations: 1. Maintain current KYC verification standards 2. Consider increasing QR verification frequency 3. Monitor for any changes in transaction patterns 4. Regular compliance score reviews recommended Confidence Level: 94% Analysis Generated: 2024-08-01T14:00:00Z ``` #### Examples ```bash # Basic vector analysis pact-entity fuse --entity alice.eth --summary # AI-powered analysis pact-entity fuse --entity alice.eth --ai-summary # Export vector data pact-entity fuse --entity alice.eth --export alice-vector.json # Generate relationship graph pact-entity fuse --entity alice.eth --graph dot --export alice-network.dot # Complete analysis with export pact-entity fuse --entity alice.eth --ai-summary --graph json --export alice-complete.json ``` ## Data Models ### Entity Model ```typescript interface Entity { id: string; type: 'individual' | 'organization' | 'wallet'; name: string; complianceScore: number; // 0-100 kycStatus: 'pending' | 'verified' | 'rejected'; amlStatus: 'pending' | 'completed' | 'failed'; riskScore: number; // 0.0-1.0 metadata: Record; created: string; // ISO timestamp updated: string; // ISO timestamp } ``` ### Relationship Model ```typescript interface Relationship { id: string; from: string; // Entity ID to: string; // Entity ID type: string; metadata: Record; status: 'active' | 'inactive' | 'suspended'; created: string; // ISO timestamp } ``` ### Timeline Event Model ```typescript interface TimelineEvent { timestamp: string; // ISO timestamp type: string; description: string; metadata: Record; severity: 'info' | 'warning' | 'error'; } ``` ### Compliance Vector Model ```typescript interface ComplianceVector { entityId: string; vector: number[]; // 8-dimensional array dimensions: { kyc_score: number; avg_risk: number; sanctions_flag: number; qr_events: number; high_value_tx: number; contract_exposure: number; token_diversity: number; anomaly_frequency: number; }; magnitude: number; checksum: string; created: string; // ISO timestamp } ``` ## Response Formats ### Success Response ```json { "success": true, "data": { /* command-specific data */ }, "proof": "pact-proof-abc123def456", // if --proof option used "timestamp": "2024-08-01T12:00:00Z" } ``` ### Error Response ```json { "success": false, "error": { "code": "ENTITY_NOT_FOUND", "message": "Entity 'alice.eth' not found", "details": { "entityId": "alice.eth", "suggestion": "Use 'pact-entity search' to find available entities" } }, "timestamp": "2024-08-01T12:00:00Z" } ``` ## Error Handling ### Error Codes | Code | Description | HTTP Equivalent | |------|-------------|-----------------| | `ENTITY_NOT_FOUND` | Entity does not exist | 404 | | `VALIDATION_ERROR` | Invalid input parameters | 400 | | `PERMISSION_DENIED` | Insufficient permissions | 403 | | `RATE_LIMIT_EXCEEDED` | Too many requests | 429 | | `INTERNAL_ERROR` | System error | 500 | | `DATABASE_ERROR` | Database connectivity issue | 503 | | `CONFIGURATION_ERROR` | Configuration problem | 500 | ### Error Handling Strategies **Retry Logic:** ```bash #!/bin/bash # Retry command with exponential backoff for i in {1..3}; do if pact-entity score --entity alice.eth --json; then break else sleep $((i * 2)) fi done ``` **Error Checking:** ```bash #!/bin/bash if ! pact-entity create --name "Alice" --json > result.json; then echo "Entity creation failed" cat result.json | jq '.error' exit 1 fi ``` ## Integration Examples ### Shell Script Integration ```bash #!/bin/bash # Batch entity processing script entities=("alice.eth" "bob.eth" "charlie.eth") output_file="compliance_report.json" echo "[]" > "$output_file" for entity in "${entities[@]}"; do echo "Processing $entity..." if score_result=$(pact-entity score --entity "$entity" --json); then # Merge result into output file jq --argjson new "$score_result" '. += [$new]' "$output_file" > tmp.json mv tmp.json "$output_file" else echo "Error processing $entity" fi done echo "Report generated: $output_file" ``` ### Python Integration ```python import subprocess import json def get_entity_score(entity_id): """Get compliance score for an entity.""" try: result = subprocess.run([ 'pact-entity', 'score', '--entity', entity_id, '--json' ], capture_output=True, text=True, check=True) return json.loads(result.stdout) except subprocess.CalledProcessError as e: error = json.loads(e.stdout) raise Exception(f"CLI Error: {error['error']['message']}") # Usage try: score_data = get_entity_score('alice.eth') print(f"Compliance Score: {score_data['score']['overall']}") except Exception as e: print(f"Error: {e}") ``` ### Node.js Integration ```javascript const { exec } = require('child_process'); const { promisify } = require('util'); const execAsync = promisify(exec); async function createEntity(name, type = 'individual') { try { const { stdout } = await execAsync( `pact-entity create --name "${name}" --type ${type} --json` ); return JSON.parse(stdout); } catch (error) { const errorData = JSON.parse(error.stdout); throw new Error(errorData.error.message); } } // Usage (async () => { try { const result = await createEntity('Alice Smith'); console.log('Entity created:', result.entity.id); } catch (error) { console.error('Error:', error.message); } })(); ``` ### REST API Wrapper ```bash #!/bin/bash # REST API wrapper using CLI entity_id="$1" operation="$2" case "$operation" in "get") pact-entity status --entity "$entity_id" --json ;; "score") pact-entity score --entity "$entity_id" --json ;; "timeline") pact-entity timeline --entity "$entity_id" --json ;; *) echo '{"error": "Unknown operation"}' exit 1 ;; esac ``` ### Monitoring Integration ```bash #!/bin/bash # Compliance monitoring script # Check system health system_status=$(pact-entity status --summary --json) entity_count=$(echo "$system_status" | jq '.data.totalEntities') avg_score=$(echo "$system_status" | jq '.data.averageScore') # Send metrics to monitoring system curl -X POST "https://monitoring.example.com/metrics" \ -H "Content-Type: application/json" \ -d "{ \"metric\": \"pact_entity_count\", \"value\": $entity_count, \"timestamp\": $(date +%s) }" curl -X POST "https://monitoring.example.com/metrics" \ -H "Content-Type: application/json" \ -d "{ \"metric\": \"pact_avg_compliance_score\", \"value\": $avg_score, \"timestamp\": $(date +%s) }" ``` --- This API reference provides comprehensive documentation for integrating PACT Entity CLI into your applications and workflows. For additional support, consult the main [README](README.md) or contact the development team.