← Back to Resources

API Reference Guide

Overview

This comprehensive API reference covers all endpoints available in our blockchain-based construction management platform. The API provides secure access to contract creation, project management, user authentication, and blockchain interactions.

Table of Contents

  1. Base Information
  2. Authentication
  3. User Management
  4. Contract Management
  5. Project APIs
  6. Check Management
  7. Document Management
  8. Blockchain Integration
  9. Search & Discovery
  10. Configuration
  11. Error Handling
  12. Rate Limiting
  13. WebSocket Events

Base Information

Base URL

https://contracting.app/api/

API Version

Current version: v1 (implicit in all endpoints)

Content Type

All API requests and responses use:

Content-Type: application/json

Authentication Header

Authorization: Bearer <token>
Cookie: session=<session_id>

Required Headers

X-CSRFToken: <csrf_token>  // Required for state-changing operations
X-Requested-With: XMLHttpRequest  // For AJAX requests

Authentication

Check Authentication Status

Get current user authentication status and capabilities.

Endpoint: GET /api/auth/status

Rate Limit: 30 requests/minute

Authentication: Optional (shows different response based on auth state)

Response (Authenticated):

{
  "authenticated": true,
  "user": {
    "id": 123,
    "email": "user@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "ethereum_address": "0x742d35Cc6639C0532fEb3C0d2C232aa1B4b79a14",
    "is_active": true
  },
  "capabilities": {
    "can_create_contracts": true,
    "can_manage_projects": true,
    "mfa_enabled": false
  },
  "web3_status": {
    "available": true,
    "degraded_mode": false,
    "network": "SEI Mainnet"
  },
  "permissions": {
    "admin": false,
    "project_creator": true
  },
  "timestamp": "2025-01-02T10:30:00.000Z"
}

Response (Not Authenticated):

{
  "authenticated": false,
  "user": null,
  "capabilities": {},
  "web3_status": {
    "available": false,
    "degraded_mode": true
  },
  "timestamp": "2025-01-02T10:30:00.000Z"
}

Multi-Factor Authentication

Setup MFA: POST /auth/mfa/setup Verify MFA: POST /auth/mfa/verify Disable MFA: POST /auth/mfa/disable

Note: MFA endpoints are under /auth/ not /api/auth/

User Management

Get User Profile

Endpoint: GET /api/user/profile

Authentication: Required

Response:

{
  "id": 123,
  "email": "user@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "company_name": "Construction Corp",
  "ethereum_address": "0x742d35Cc6639C0532fEb3C0d2C232aa1B4b79a14",
  "created_at": "2024-01-15T09:30:00.000Z",
  "last_seen": "2025-01-02T10:25:00.000Z",
  "mfa_enabled": false,
  "email_verified": true,
  "wallets": [
    {
      "id": 1,
      "address": "0x742d35Cc6639C0532fEb3C0d2C232aa1B4b79a14",
      "wallet_provider": "MetaMask",
      "is_primary": true,
      "network_name": "SEI Mainnet"
    }
  ]
}

Update User Profile

Endpoint: PUT /api/user/profile

Authentication: Required

Request Body:

{
  "first_name": "John",
  "last_name": "Doe",
  "company_name": "Updated Corp Name",
  "phone_number": "+1-555-123-4567"
}

Response:

{
  "success": true,
  "message": "Profile updated successfully",
  "updated_fields": ["company_name", "phone_number"]
}

Contract Management

Create Contract

Create a new smart contract for project management.

Endpoint: POST /api/contracts/create

Authentication: Required

Rate Limit: 5 requests/minute

Request Body:

{
  "title": "Downtown Office Building",
  "description": "50-story commercial construction project",
  "total_amount": "1000.0",
  "participants": [
    {
      "address": "0x1234...",
      "role": "GENERAL_CONTRACTOR",
      "email": "contractor@example.com"
    },
    {
      "address": "0x5678...",
      "role": "OWNER",
      "email": "owner@example.com"
    }
  ],
  "phases": [
    {
      "name": "Foundation",
      "percentage": 25,
      "estimated_duration": "30 days"
    },
    {
      "name": "Framing",
      "percentage": 30,
      "estimated_duration": "45 days"
    }
  ],
  "approval_threshold": 2
}

Response:

{
  "success": true,
  "contract_id": 789,
  "contract_address": "0x9abc...",
  "transaction_hash": "0xdef0...",
  "estimated_gas_cost": "2,150,000",
  "message": "Contract created successfully"
}

Get Contract Details

Endpoint: GET /api/contracts/{contract_id}

Authentication: Required

Response:

{
  "id": 789,
  "title": "Downtown Office Building",
  "description": "50-story commercial construction project",
  "status": "active",
  "address": "0x9abc...",
  "total_amount": "1000.0",
  "created_at": "2025-01-01T15:30:00.000Z",
  "creator": {
    "id": 123,
    "email": "user@example.com",
    "name": "John Doe"
  },
  "participants": [
    {
      "address": "0x1234...",
      "role": "GENERAL_CONTRACTOR",
      "status": "active",
      "joined_at": "2025-01-01T15:35:00.000Z"
    }
  ],
  "phases": [
    {
      "id": 1,
      "name": "Foundation",
      "status": "in_progress",
      "percentage": 25,
      "completed": false
    }
  ],
  "blockchain_status": {
    "deployed": true,
    "confirmed": true,
    "last_sync": "2025-01-02T10:28:00.000Z"
  }
}

List User Contracts

Endpoint: GET /api/contracts

Authentication: Required

Query Parameters:

Response:

{
  "contracts": [
    {
      "id": 789,
      "title": "Downtown Office Building",
      "status": "active",
      "total_amount": "1000.0",
      "participants_count": 3,
      "created_at": "2025-01-01T15:30:00.000Z"
    }
  ],
  "pagination": {
    "total": 15,
    "limit": 20,
    "offset": 0,
    "has_next": false
  }
}

Project APIs

Create Project Contract

Create a new project using the contract factory with modular architecture.

Endpoint: POST /api/projects/create

Authentication: Required

Rate Limit: 5 requests/minute

Request Body:

{
  "contentHash": "0x1234567890abcdef...",
  "creator": "0x742d35Cc6639C0532fEb3C0d2C232aa1B4b79a14",
  "totalContractAmount": "1000.0",
  "participants": [
    "0x1234...",
    "0x5678...",
    "0x9abc..."
  ],
  "roles": [
    "GENERAL_CONTRACTOR_ROLE",
    "ARCHITECT_ROLE", 
    "OWNER_ROLE"
  ],
  "requiredApprovers": [
    "0x1234...",
    "0x9abc..."
  ],
  "phasePercentages": [25, 25, 25, 25],
  "approvalThreshold": 2,
  "initialDocuments": [
    {
      "documentName": "Project Blueprint",
      "documentHash": "0xabc123...",
      "ipfsHash": "QmX5Z7...",
      "verified": false
    }
  ]
}

Response:

{
  "success": true,
  "projectId": 12,
  "contractAddress": "0xdef456...",
  "modules": {
    "projectCore": "0xdef456...",
    "paymentManager": "0x789abc...",
    "documentManager": "0x123def...",
    "securityManager": "0x456789...",
    "complianceManager": "0x789012...",
    "milestoneManager": "0x345678..."
  },
  "transactionHash": "0x987654...",
  "message": "Project contract created successfully"
}

Get Project Details

Endpoint: GET /api/projects/{project_address}/details

Authentication: Required

Response:

{
  "project_id": 12,
  "address": "0xdef456...",
  "name": "Commercial Building Project",
  "description": "50-story office building construction",
  "status": "active",
  "total_value": "1000.0",
  "created_at": "2025-01-01T15:30:00.000Z",
  "creator": "0x742d35Cc6639C0532fEb3C0d2C232aa1B4b79a14",
  "modules": {
    "projectCore": "0xdef456...",
    "paymentManager": "0x789abc...",
    "documentManager": "0x123def...",
    "securityManager": "0x456789...",
    "complianceManager": "0x789012...",
    "milestoneManager": "0x345678..."
  },
  "participants": [
    {
      "address": "0x1234...",
      "role": "GENERAL_CONTRACTOR_ROLE",
      "active": true,
      "added_at": "2025-01-01T15:35:00.000Z"
    }
  ],
  "milestones": [
    {
      "id": 1,
      "name": "Foundation Complete",
      "percentage": 25,
      "status": "pending",
      "deadline": "2025-02-01T00:00:00.000Z"
    }
  ],
  "blockchain_status": {
    "deployed": true,
    "fully_initialized": true,
    "last_sync": "2025-01-02T10:30:00.000Z"
  }
}

Attach Document to Project

Endpoint: POST /api/projects/{project_address}/attach-document

Authentication: Required

Request Body:

{
  "documentName": "Updated Blueprint",
  "documentHash": "0xnew123...",
  "ipfsHash": "QmNewHash...",
  "category": "BLUEPRINT",
  "description": "Revised architectural plans"
}

Response:

{
  "success": true,
  "document_id": 45,
  "transaction_hash": "0x123abc...",
  "message": "Document attached successfully"
}

Queue Payments

Endpoint: POST /api/projects/{project_address}/queue-payments

Authentication: Required

Request Body:

{
  "payments": [
    {
      "payee": "0x1234...",
      "amount": "250.0",
      "milestone_id": 1,
      "description": "Foundation completion payment"
    }
  ]
}

Withdraw Payment

Endpoint: POST /api/projects/{project_address}/withdraw-payment

Authentication: Required

Request Body:

{
  "amount": "250.0",
  "payee": "0x1234..."
}

Get User Projects

Endpoint: GET /api/user/projects

Authentication: Required

Query Parameters:

Response:

{
  "projects": [
    {
      "id": 12,
      "address": "0xdef456...",
      "name": "Commercial Building Project",
      "status": "active",
      "total_value": "1000.0",
      "created_at": "2025-01-01T15:30:00.000Z",
      "participants_count": 3
    }
  ],
  "total": 5
}

Check Management

Create Check

Endpoint: POST /api/checks/create

Authentication: Required

Request Body:

{
  "recipient_id": 456,
  "amount": "5000.00",
  "memo": "Progress payment for foundation work",
  "project_contract_id": 789,  // Optional
  "due_date": "2025-01-15",
  "require_signature": false
}

Response:

{
  "success": true,
  "check_id": 1001,
  "check_number": "CHK-20250102-001",
  "status": "pending",
  "blockchain_linked": true,
  "contract_address": "0x9abc...",  // If linked to project
  "message": "Check created successfully"
}

Get Check Statistics

Endpoint: GET /api/checks/statistics

Authentication: Required

Response:

{
  "total_checks": 45,
  "total_amount": "125000.00",
  "pending_checks": 12,
  "pending_amount": "35000.00",
  "completed_checks": 33,
  "completed_amount": "90000.00",
  "this_month": {
    "checks_created": 8,
    "total_amount": "22000.00"
  },
  "blockchain_linked": 15,
  "traditional_checks": 30
}

List Checks

Endpoint: GET /api/checks

Authentication: Required

Query Parameters:

Response:

{
  "checks": [
    {
      "id": 1001,
      "check_number": "CHK-20250102-001",
      "amount": "5000.00",
      "recipient": {
        "id": 456,
        "name": "ABC Construction",
        "email": "payments@abcconstruction.com"
      },
      "memo": "Progress payment for foundation work",
      "status": "pending",
      "created_at": "2025-01-02T09:15:00.000Z",
      "due_date": "2025-01-15T00:00:00.000Z",
      "blockchain_linked": true,
      "contract_address": "0x9abc..."
    }
  ],
  "pagination": {
    "total": 45,
    "limit": 20,
    "offset": 0,
    "has_next": true
  }
}

Document Management

Upload Document to IPFS

Endpoint: POST /api/ipfs/upload

Authentication: Required

Content Type: multipart/form-data

Request Body:

file: <binary file data>

Response:

{
  "success": true,
  "ipfs_hash": "QmX5Z7K2R3...",
  "file_size": 2048576,
  "file_name": "blueprint.pdf",
  "content_type": "application/pdf",
  "upload_timestamp": "2025-01-02T10:30:00.000Z"
}

Create Document Record

Endpoint: POST /api/documents

Authentication: Required

Request Body:

{
  "name": "Project Blueprint",
  "description": "Architectural plans for main building",
  "ipfs_hash": "QmX5Z7K2R3...",
  "content_hash": "0xabc123...",
  "category": "BLUEPRINT",
  "project_id": 12,
  "requires_approval": true
}

Response:

{
  "success": true,
  "document_id": 67,
  "status": "pending_verification",
  "created_at": "2025-01-02T10:35:00.000Z"
}

Get Document

Endpoint: GET /api/ipfs/{ipfs_hash}

Authentication: Required

Response: Binary file download or redirect to IPFS gateway

Blockchain Integration

Get Contract Addresses

Get all deployed smart contract addresses for frontend initialization.

Endpoint: GET /api/config/contract-addresses

Authentication: Optional

Response:

{
  "factoryAddress": "0x0165878A594ca255338adfa4d48449f69242Eb8F",
  "projectFactoryV2Address": "0x0165878A594ca255338adfa4d48449f69242Eb8F",
  "projectCoreAddress": "0x3D35F424692f21fB5B3f3f5E15bcBc97D0b910aa",
  "paymentManagerAddress": "0xF9d241D1B52Ba6404e388B4ACd7e38F5032f2380",
  "documentManagerAddress": "0x9fE46736679d2D9a65F0992F2272dE9f3c7fa6e0",
  "securityManagerAddress": "0xDc64a140Aa3E981100a9becA4E685f962f0cF6C9",
  "complianceManagerAddress": "0xCf7Ed3AccA5a467e9e704C703E8D87F634fB0Fc9",
  "milestoneManagerAddress": "0xA50405Af54ceBb24Adc01073cf7cfd4860CeD145"
}

Get Factory Health

Endpoint: GET /api/factory/health

Authentication: Required

Response:

{
  "healthy": true,
  "factory_address": "0x0165878A594ca255338adfa4d48449f69242Eb8F",
  "network": "SEI Mainnet",
  "block_height": 1234567,
  "gas_price_gwei": "25.5",
  "last_check": "2025-01-02T10:30:00.000Z"
}

Get Factory Statistics

Endpoint: GET /api/factory/stats

Authentication: Required

Response:

{
  "total_projects_created": 1247,
  "total_value_locked": "15750000.50",
  "active_projects": 892,
  "completed_projects": 355,
  "factory_version": "2.1.0",
  "deployment_date": "2024-12-15T10:00:00.000Z"
}

Get Price Information

Ethereum Price: Endpoint: GET /api/price/ethereum

SEI Price: Endpoint: GET /api/price/native

Rate Limit: 60 requests/minute

Response:

{
  "price_usd": "3456.78",
  "price_change_24h": "+2.45%",
  "last_updated": "2025-01-02T10:28:00.000Z",
  "source": "coingecko"
}

Search & Discovery

Search across contracts, users, and projects.

Endpoint: POST /api/search

Authentication: Required

Rate Limit: 20 requests/minute

Request Body:

{
  "query": "office building",
  "type": "all",  // all, contracts, users, projects
  "limit": 20,
  "offset": 0
}

Response:

{
  "contracts": [
    {
      "id": 789,
      "title": "Downtown Office Building",
      "description": "50-story commercial building...",
      "status": "active",
      "total_amount": 1000.0,
      "created_at": "2025-01-01T15:30:00.000Z"
    }
  ],
  "projects": [
    {
      "id": 12,
      "name": "Office Complex Project",
      "description": "Modern office complex...",
      "total_value": "2500.0",
      "status": "active"
    }
  ],
  "users": [],
  "query": "office building",
  "total_results": 2,
  "timestamp": "2025-01-02T10:30:00.000Z",
  "search_type": "all"
}

Configuration

Get Application Configuration

Endpoint: GET /api/config

Authentication: Optional (limited info for unauthenticated)

Response:

{
  "app_version": "2.1.0",
  "api_version": "v1",
  "network": {
    "name": "SEI Mainnet",
    "chain_id": 1329,
    "currency": "SEI"
  },
  "features": {
    "mfa_enabled": true,
    "passkey_support": true,
    "blockchain_integration": true,
    "ipfs_storage": true
  },
  "limits": {
    "max_file_size": "10MB",
    "max_participants": 100,
    "max_contract_value": "1000000000"
  }
}

Error Handling

Standard Error Response Format

All API errors follow this structure:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input parameters",
    "details": {
      "field": "email",
      "reason": "Invalid email format"
    }
  },
  "timestamp": "2025-01-02T10:30:00.000Z",
  "request_id": "req_123456789"
}

HTTP Status Codes

Code Meaning Description
200 OK Request successful
201 Created Resource created successfully
400 Bad Request Invalid request parameters
401 Unauthorized Authentication required
403 Forbidden Insufficient permissions
404 Not Found Resource not found
409 Conflict Resource already exists
422 Unprocessable Entity Validation failed
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Server error
503 Service Unavailable Temporary service issue

Common Error Codes

Code Description
VALIDATION_ERROR Input validation failed
AUTHENTICATION_REQUIRED User must be logged in
INSUFFICIENT_PERMISSIONS User lacks required permissions
RATE_LIMIT_EXCEEDED Too many requests
RESOURCE_NOT_FOUND Requested resource doesn't exist
BLOCKCHAIN_ERROR Smart contract interaction failed
NETWORK_ERROR Network connectivity issue
INSUFFICIENT_BALANCE Not enough funds for operation

Rate Limiting

Rate Limit Headers

All responses include rate limiting information:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1609459200

Rate Limits by Endpoint Category

Category Limit Window
Authentication 10/minute Per IP
Search 20/minute Per user
Contract Creation 5/minute Per user
File Upload 10/minute Per user
General API 60/minute Per user
Price Data 60/minute Per IP

Rate Limit Exceeded Response

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded",
    "details": {
      "limit": 60,
      "window": "minute",
      "reset_at": "2025-01-02T10:31:00.000Z"
    }
  }
}

WebSocket Events

Connection

Connect to WebSocket for real-time updates:

wss://contracting.app/socket.io/

Authentication

WebSocket connections use the same session authentication as HTTP APIs.

Event Types

Contract Events

// Contract created
{
  "event": "contract_created",
  "data": {
    "contract_id": 789,
    "address": "0x9abc...",
    "creator_id": 123
  }
}

// Contract status changed
{
  "event": "contract_status_changed", 
  "data": {
    "contract_id": 789,
    "old_status": "pending",
    "new_status": "active"
  }
}

Payment Events

// Payment queued
{
  "event": "payment_queued",
  "data": {
    "project_address": "0xdef456...",
    "payee": "0x1234...",
    "amount": "250.0",
    "milestone_id": 1
  }
}

// Payment withdrawn
{
  "event": "payment_withdrawn",
  "data": {
    "project_address": "0xdef456...",
    "payee": "0x1234...",
    "amount": "250.0",
    "transaction_hash": "0x987..."
  }
}

Document Events

// Document uploaded
{
  "event": "document_uploaded",
  "data": {
    "document_id": 67,
    "project_address": "0xdef456...",
    "name": "Updated Blueprint",
    "uploader": "0x5678..."
  }
}

// Document verified
{
  "event": "document_verified",
  "data": {
    "document_id": 67,
    "verified_by": "0x9abc...",
    "verification_timestamp": "2025-01-02T11:00:00.000Z"
  }
}

Subscribing to Events

// Connect to WebSocket
const socket = io('wss://contracting.app');

// Subscribe to contract events for specific contract
socket.emit('subscribe', {
  event_type: 'contract_events',
  contract_id: 789
});

// Subscribe to project events
socket.emit('subscribe', {
  event_type: 'project_events', 
  project_address: '0xdef456...'
});

// Subscribe to user-specific events
socket.emit('subscribe', {
  event_type: 'user_events'
});

SDK Examples

JavaScript/TypeScript

// Initialize API client
import { CheckingAppAPI } from '@checkingapp/api-client';

const api = new CheckingAppAPI({
  baseURL: 'https://contracting.app/api',
  apiKey: 'your-api-key', // If using API key auth
});

// Create a contract
const contract = await api.contracts.create({
  title: 'New Construction Project',
  description: 'Office building construction',
  total_amount: '1000.0',
  participants: [
    { address: '0x1234...', role: 'CONTRACTOR' }
  ]
});

// Get user's contracts
const contracts = await api.contracts.list({
  status: 'active',
  limit: 10
});

// Subscribe to real-time events
api.events.on('contract_created', (data) => {
  console.log('New contract created:', data);
});

Python

import httpx
from typing import Dict, Any

class CheckingAppClient:
    def __init__(self, base_url: str, session_token: str = None):
        self.base_url = base_url
        self.session = httpx.AsyncClient()
        if session_token:
            self.session.cookies.set('session', session_token)

    async def create_contract(self, data: Dict[str, Any]) -> Dict[str, Any]:
        response = await self.session.post(
            f"{self.base_url}/contracts/create",
            json=data
        )
        response.raise_for_status()
        return response.json()

    async def get_contracts(self, status: str = None) -> Dict[str, Any]:
        params = {"status": status} if status else {}
        response = await self.session.get(
            f"{self.base_url}/contracts",
            params=params
        )
        response.raise_for_status()
        return response.json()

# Usage
client = CheckingAppClient('https://contracting.app/api')
contracts = await client.get_contracts(status='active')

Testing

Test Environment

Base URL: https://staging.contracting.app/api/

Sample Test Data

Use these test addresses on SEI testnet:

{
  "test_addresses": [
    "0x742d35Cc6639C0532fEb3C0d2C232aa1B4b79a14",
    "0x8ba1f109551bD432803012645Hac136c60143Ba2",
    "0x1234567890123456789012345678901234567890"
  ],
  "test_tokens": {
    "SEI": "1000.0",
    "testnet_faucet": "https://faucet.sei-testnet.com"
  }
}

Postman Collection

Import our Postman collection for easy API testing: Download Collection

Support

API Support

Rate Limit Issues

Contact support for higher rate limits with justification for business use cases.

Security Issues

Report security issues to: security@contracting.app

This API documentation is regularly updated. Last updated: January 2025

← Back to Resources