API Reference

FractaLedger API Reference

Complete documentation of all API endpoints provided by FractaLedger.

Table of Contents

Authentication

FractaLedger uses JWT (JSON Web Tokens) for authentication. To access protected endpoints, you need to include the JWT token in the Authorization header of your requests.

Login

POST /api/auth/login

Authenticate a user and get a JWT token.

Request Body

{
  "username": "admin",
  "password": "your-password"
}

Response

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": "1d"
}

Wallet Management

Register a New Wallet

POST /api/wallets

Register a new blockchain wallet with the system.

Request Body

{
  "blockchain": "bitcoin",
  "name": "btc_wallet_1",
  "network": "mainnet",
  "walletAddress": "bc1q...",
  "secretEnvVar": "BTC_WALLET_1_SECRET",
  "transceiver": {
    "method": "callback",
    "callbackModule": "./transceivers/utxo-transceiver.js",
    "monitoringInterval": 60000,
    "autoMonitor": true
  }
}

Response

{
  "success": true,
  "wallet": {
    "blockchain": "bitcoin",
    "name": "btc_wallet_1",
    "network": "mainnet",
    "walletAddress": "bc1q...",
    "secretEnvVar": "BTC_WALLET_1_SECRET"
  },
  "messages": [
    {
      "type": "info",
      "code": "INFO_002",
      "message": "Wallet created successfully",
      "data": {
        "blockchain": "bitcoin",
        "name": "btc_wallet_1"
      },
      "timestamp": "2025-03-13T12:00:00Z"
    }
  ]
}

List All Registered Wallets

GET /api/wallets

Get a list of all registered wallets.

Response

{
  "wallets": [
    {
      "blockchain": "bitcoin",
      "name": "btc_wallet_1",
      "network": "mainnet",
      "walletAddress": "bc1q..."
    },
    {
      "blockchain": "litecoin",
      "name": "ltc_wallet_1",
      "network": "mainnet",
      "walletAddress": "ltc1q..."
    }
  ]
}

Get Wallet Details

GET /api/wallets/:blockchain/:name

Get details for a specific wallet.

Parameters

  • blockchain - The blockchain type (e.g., bitcoin, litecoin)
  • name - The wallet name

Response

{
  "wallet": {
    "blockchain": "bitcoin",
    "name": "btc_wallet_1",
    "network": "mainnet",
    "walletAddress": "bc1q...",
    "balance": 1.5
  }
}

Get Read-Only Wallet Access

GET /api/wallets/:blockchain/:name/read-only

Get read-only information about a wallet, including aggregate internal balance.

Parameters

  • blockchain - The blockchain type (e.g., bitcoin, litecoin)
  • name - The wallet name

Response

{
  "blockchain": "bitcoin",
  "name": "btc_wallet_1",
  "address": "bc1q...",
  "balance": 1.5,
  "aggregateInternalBalance": 1.2,
  "excessBalance": 0.3,
  "baseInternalWalletId": "base_wallet_bitcoin_btc_wallet_1"
}

Internal Wallet Management

Create a New Internal Wallet

POST /api/internal-wallets

Create a new internal wallet mapped to a primary wallet.

Request Body

{
  "id": "internal_wallet_1",
  "blockchain": "bitcoin",
  "primaryWalletName": "btc_wallet_1",
  "description": "Customer wallet for user123",
  "metadata": {
    "userId": "user123",
    "customerType": "premium"
  }
}

Response

{
  "success": true,
  "internalWallet": {
    "id": "internal_wallet_1",
    "blockchain": "bitcoin",
    "primaryWalletName": "btc_wallet_1",
    "description": "Customer wallet for user123",
    "balance": 0,
    "metadata": {
      "userId": "user123",
      "customerType": "premium"
    },
    "createdAt": "2025-03-13T12:00:00Z"
  },
  "messages": [
    {
      "type": "info",
      "code": "INFO_003",
      "message": "Internal wallet created successfully",
      "data": {
        "id": "internal_wallet_1",
        "blockchain": "bitcoin",
        "primaryWalletName": "btc_wallet_1"
      },
      "timestamp": "2025-03-13T12:00:00Z"
    }
  ]
}

List All Internal Wallets

GET /api/internal-wallets

Get a list of all internal wallets.

Response

{
  "internalWallets": [
    {
      "id": "internal_wallet_1",
      "blockchain": "bitcoin",
      "primaryWalletName": "btc_wallet_1",
      "description": "Customer wallet for user123",
      "balance": 0.5,
      "metadata": {
        "userId": "user123",
        "customerType": "premium"
      },
      "createdAt": "2025-03-13T12:00:00Z"
    },
    {
      "id": "internal_wallet_2",
      "blockchain": "bitcoin",
      "primaryWalletName": "btc_wallet_1",
      "description": "Customer wallet for user456",
      "balance": 0.3,
      "metadata": {
        "userId": "user456",
        "customerType": "standard"
      },
      "createdAt": "2025-03-13T12:30:00Z"
    }
  ]
}

Get Internal Wallet Details

GET /api/internal-wallets/:id

Get details for a specific internal wallet.

Parameters

  • id - The internal wallet ID

Response

{
  "internalWallet": {
    "id": "internal_wallet_1",
    "blockchain": "bitcoin",
    "primaryWalletName": "btc_wallet_1",
    "description": "Customer wallet for user123",
    "balance": 0.5,
    "metadata": {
      "userId": "user123",
      "customerType": "premium"
    },
    "createdAt": "2025-03-13T12:00:00Z"
  }
}

Get Internal Wallet Balance

GET /api/internal-wallets/:id/balance

Get the balance of a specific internal wallet.

Parameters

  • id - The internal wallet ID

Response

{
  "id": "internal_wallet_1",
  "balance": 0.5,
  "blockchain": "bitcoin",
  "primaryWalletName": "btc_wallet_1"
}

Fund an Internal Wallet

POST /api/internal-wallets/:id/fund

Fund an internal wallet (simulate deposit).

Parameters

  • id - The internal wallet ID

Request Body

{
  "amount": 0.1
}

Response

{
  "success": true,
  "internalWallet": {
    "id": "internal_wallet_1",
    "blockchain": "bitcoin",
    "primaryWalletName": "btc_wallet_1",
    "balance": 0.6,
    "previousBalance": 0.5
  },
  "messages": [
    {
      "type": "info",
      "code": "INFO_004",
      "message": "Internal wallet funded successfully",
      "data": {
        "id": "internal_wallet_1",
        "amount": 0.1,
        "newBalance": 0.6
      },
      "timestamp": "2025-03-13T12:00:00Z"
    }
  ]
}

Withdraw from an Internal Wallet

POST /api/internal-wallets/:id/withdraw

Withdraw funds from an internal wallet to an external address.

Parameters

  • id - The internal wallet ID

Request Body

{
  "toAddress": "bc1q...",
  "amount": 0.1,
  "fee": 0.0001
}

Response

{
  "success": true,
  "withdrawal": {
    "id": "withdrawal_123",
    "internalWalletId": "internal_wallet_1",
    "toAddress": "bc1q...",
    "amount": 0.1,
    "fee": 0.0001,
    "txid": "abcdef1234567890...",
    "status": "broadcasted",
    "timestamp": "2025-03-13T12:00:00Z"
  },
  "messages": [
    {
      "type": "info",
      "code": "INFO_005",
      "message": "Withdrawal processed successfully",
      "data": {
        "id": "withdrawal_123",
        "internalWalletId": "internal_wallet_1",
        "amount": 0.1,
        "txid": "abcdef1234567890..."
      },
      "timestamp": "2025-03-13T12:00:00Z"
    }
  ]
}

Transactions

Internal Transfer

POST /api/transactions/internal-transfer

Transfer funds between internal wallets that are mapped to the same primary on-chain wallet.

Request Body

{
  "fromInternalWalletId": "internal_wallet_1",
  "toInternalWalletId": "internal_wallet_2",
  "amount": 0.1,
  "memo": "Payment for services"
}

Response

{
  "success": true,
  "transfer": {
    "id": "transfer_123",
    "fromWalletId": "internal_wallet_1",
    "toWalletId": "internal_wallet_2",
    "amount": 0.1,
    "memo": "Payment for services",
    "timestamp": "2025-03-13T12:00:00Z"
  },
  "messages": [
    {
      "type": "info",
      "code": "INFO_001",
      "message": "Internal transfer processed successfully",
      "data": {
        "fromWalletId": "internal_wallet_1",
        "toWalletId": "internal_wallet_2",
        "amount": 0.1
      },
      "timestamp": "2025-03-13T12:00:00Z"
    }
  ]
}

List All Transactions

GET /api/transactions

Get a list of all transactions.

Query Parameters

  • page - Page number (default: 1)
  • limit - Number of transactions per page (default: 10)
  • type - Transaction type (internal, withdrawal, deposit)
  • walletId - Filter by wallet ID
  • startDate - Filter by start date (ISO format)
  • endDate - Filter by end date (ISO format)

Response

{
  "transactions": [
    {
      "id": "transfer_123",
      "type": "internal",
      "fromWalletId": "internal_wallet_1",
      "toWalletId": "internal_wallet_2",
      "amount": 0.1,
      "memo": "Payment for services",
      "timestamp": "2025-03-13T12:00:00Z"
    },
    {
      "id": "withdrawal_123",
      "type": "withdrawal",
      "internalWalletId": "internal_wallet_1",
      "toAddress": "bc1q...",
      "amount": 0.1,
      "fee": 0.0001,
      "txid": "abcdef1234567890...",
      "status": "broadcasted",
      "timestamp": "2025-03-13T11:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "totalItems": 2,
    "totalPages": 1
  }
}

Get Pending Transactions

GET /api/transactions/pending

Retrieves a list of transactions that are ready to be broadcast to the blockchain network. These transactions have been created and signed but not yet broadcast.

Response

{
  "pendingTransactions": [
    {
      "txid": "0x1234567890abcdef",
      "txHex": "0100000001abcdef...",
      "blockchain": "bitcoin",
      "primaryWalletName": "btc_wallet_1",
      "status": "ready",
      "timestamp": "2025-03-12T12:00:00Z",
      "metadata": {
        "internalWalletId": "internal_wallet_1",
        "toAddress": "bc1q...",
        "amount": 0.1,
        "fee": 0.0001
      }
    }
  ]
}

Note: The txHex field contains the raw transaction in hexadecimal format, which is ready to be broadcast to the blockchain network. This transaction has been fully created and signed by the system.

Submit Transaction Results

POST /api/transactions/results

Submits the results of a transaction broadcast that was performed externally. This endpoint is used to update the system with the status of a transaction after it has been broadcast to the blockchain network.

Request Body

{
  "txid": "0x1234567890abcdef",
  "success": true,
  "blockHeight": 700000,
  "confirmations": 1,
  "error": null
}

Response

{
  "success": true,
  "transaction": {
    "txid": "0x1234567890abcdef",
    "status": "confirmed",
    "blockHeight": 700000,
    "confirmations": 1,
    "timestamp": "2025-03-12T12:00:00Z"
  },
  "messages": [
    {
      "type": "info",
      "code": "INFO_006",
      "message": "Transaction results recorded successfully",
      "data": {
        "txid": "0x1234567890abcdef",
        "status": "confirmed"
      },
      "timestamp": "2025-03-13T12:00:00Z"
    }
  ]
}

Transaction Broadcasting Flow

FractaLedger uses a transceiver architecture that separates transaction creation/signing from the actual blockchain interaction. The complete transaction flow is as follows:

  1. Transaction Creation: When you use endpoints like /api/transactions/withdraw, the system creates a transaction with the specified parameters, signs it with the wallet's private key, generates the raw transaction hex, assigns a transaction ID, and stores this information in the pending transactions map.
  2. Transaction Retrieval: Your application retrieves pending transactions via GET /api/transactions/pending.
  3. External Broadcasting: Your application is responsible for broadcasting these transactions to the blockchain network using your own infrastructure or third-party services.
  4. Result Submission: After broadcasting, your application reports the results back to FractaLedger via POST /api/transactions/results.

This architecture provides several benefits:

  • Flexibility: You can implement your own broadcasting logic.
  • Security: Sensitive operations like broadcasting can be handled in a controlled environment.
  • Customization: Different broadcasting methods can be used for different scenarios.
  • Separation of Concerns: Transaction creation is separate from blockchain interaction.

Wallet Monitoring

Get All Monitored Wallets

GET /api/wallets/monitoring

Get a list of all wallets that are currently being monitored.

Response

{
  "monitoredWallets": [
    {
      "blockchain": "bitcoin",
      "walletName": "btc_wallet_1",
      "walletAddress": "bc1q...",
      "status": "monitoring",
      "startedAt": "2025-03-13T12:00:00Z",
      "method": "spv",
      "config": {
        "server": "electrum.blockstream.info",
        "port": 50002,
        "protocol": "ssl"
      }
    },
    {
      "blockchain": "litecoin",
      "walletName": "ltc_wallet_1",
      "walletAddress": "ltc1q...",
      "status": "monitoring",
      "startedAt": "2025-03-13T12:15:00Z",
      "method": "spv",
      "config": {
        "server": "electrum-ltc.bysh.me",
        "port": 50002,
        "protocol": "ssl"
      }
    }
  ],
  "messages": [
    {
      "type": "info",
      "code": "INFO_009",
      "message": "Retrieved monitored wallets",
      "data": {
        "count": 2
      },
      "timestamp": "2025-03-13T12:30:00Z"
    }
  ]
}

Start Monitoring a Wallet Address

POST /api/wallets/:blockchain/:name/monitor

Start monitoring a wallet address for incoming transactions.

Parameters

  • blockchain - The blockchain type (e.g., bitcoin, litecoin)
  • name - The wallet name

Response

{
  "success": true,
  "monitoring": {
    "blockchain": "bitcoin",
    "walletName": "btc_wallet_1",
    "walletAddress": "bc1q...",
    "status": "monitoring",
    "startedAt": "2025-03-13T12:00:00Z"
  },
  "messages": [
    {
      "type": "info",
      "code": "INFO_007",
      "message": "Wallet monitoring started",
      "data": {
        "blockchain": "bitcoin",
        "walletName": "btc_wallet_1"
      },
      "timestamp": "2025-03-13T12:00:00Z"
    }
  ]
}

Stop Monitoring a Wallet Address

DELETE /api/wallets/:blockchain/:name/monitor

Stop monitoring a wallet address.

Parameters

  • blockchain - The blockchain type (e.g., bitcoin, litecoin)
  • name - The wallet name

Response

{
  "success": true,
  "monitoring": {
    "blockchain": "bitcoin",
    "walletName": "btc_wallet_1",
    "walletAddress": "bc1q...",
    "status": "stopped",
    "stoppedAt": "2025-03-13T12:30:00Z"
  },
  "messages": [
    {
      "type": "info",
      "code": "INFO_008",
      "message": "Wallet monitoring stopped",
      "data": {
        "blockchain": "bitcoin",
        "walletName": "btc_wallet_1"
      },
      "timestamp": "2025-03-13T12:30:00Z"
    }
  ]
}

Get Transaction History for a Wallet

GET /api/wallets/:blockchain/:name/transactions

Get transaction history for a specific wallet.

Parameters

  • blockchain - The blockchain type (e.g., bitcoin, litecoin)
  • name - The wallet name

Query Parameters

  • page - Page number (default: 1)
  • limit - Number of transactions per page (default: 10)
  • startDate - Filter by start date (ISO format)
  • endDate - Filter by end date (ISO format)

Response

{
  "transactions": [
    {
      "txid": "abcdef1234567890...",
      "blockHeight": 700000,
      "timestamp": "2025-03-13T12:00:00Z",
      "amount": 0.1,
      "fee": 0.0001,
      "confirmations": 10,
      "type": "incoming"
    },
    {
      "txid": "0987654321fedcba...",
      "blockHeight": 699990,
      "timestamp": "2025-03-13T11:30:00Z",
      "amount": 0.2,
      "fee": 0.0001,
      "confirmations": 20,
      "type": "outgoing"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "totalItems": 2,
    "totalPages": 1
  }
}

Chaincode Management

List Available Chaincode Templates

GET /api/chaincode/templates

Get a list of all available chaincode templates.

Response

{
  "templates": [
    {
      "id": "default",
      "name": "Default Template",
      "description": "Basic functionality for managing internal wallets and transactions."
    },
    {
      "id": "merchant-fee",
      "name": "Merchant Fee Template",
      "description": "Specialized functionality for merchant fee collection use cases."
    },
    {
      "id": "employee-payroll",
      "name": "Employee Payroll Template",
      "description": "Specialized functionality for employee payment use cases."
    }
  ]
}

Create a Custom Chaincode

POST /api/chaincode/custom

Create a custom chaincode based on a template.

Request Body

{
  "templateId": "merchant-fee",
  "customId": "my-merchant-fee"
}

Response

{
  "success": true,
  "chaincode": {
    "id": "my-merchant-fee",
    "templateId": "merchant-fee",
    "path": "/path/to/chaincode/custom/my-merchant-fee"
  },
  "messages": [
    {
      "type": "info",
      "code": "INFO_009",
      "message": "Custom chaincode created successfully",
      "data": {
        "id": "my-merchant-fee",
        "templateId": "merchant-fee"
      },
      "timestamp": "2025-03-13T12:00:00Z"
    }
  ]
}

Update a Custom Chaincode

PUT /api/chaincode/custom/:id

Update a custom chaincode.

Parameters

  • id - The custom chaincode ID

Request Body

{
  "filePath": "index.js",
  "content": "// Updated chaincode content\nconst { Contract } = require('fabric-contract-api');\n\nclass MerchantFeeContract extends Contract {\n  // ...\n}"
}

Response

{
  "success": true,
  "chaincode": {
    "id": "my-merchant-fee",
    "path": "/path/to/chaincode/custom/my-merchant-fee",
    "updatedFile": "index.js"
  },
  "messages": [
    {
      "type": "info",
      "code": "INFO_010",
      "message": "Custom chaincode updated successfully",
      "data": {
        "id": "my-merchant-fee",
        "updatedFile": "index.js"
      },
      "timestamp": "2025-03-13T12:00:00Z"
    }
  ]
}

Deploy a Custom Chaincode

POST /api/chaincode/custom/:id/deploy

Deploy a custom chaincode to the Hyperledger Fabric network.

Parameters

  • id - The custom chaincode ID

Response

{
  "success": true,
  "deployment": {
    "id": "my-merchant-fee",
    "status": "deployed",
    "timestamp": "2025-03-13T12:00:00Z"
  },
  "messages": [
    {
      "type": "info",
      "code": "INFO_011",
      "message": "Custom chaincode deployed successfully",
      "data": {
        "id": "my-merchant-fee"
      },
      "timestamp": "2025-03-13T12:00:00Z"
    }
  ]
}

Reconciliation

Get Reconciliation Configuration

GET /api/reconciliation/config

Get the current reconciliation configuration.

Response

{
  "config": {
    "strategy": "afterTransaction",
    "scheduledFrequency": 3600000,
    "warningThreshold": 0.00001,
    "strictMode": false
  }
}

Reconcile a Specific Wallet

POST /api/reconciliation/wallet/:blockchain/:name

Manually trigger reconciliation for a specific wallet.

Parameters

  • blockchain - The blockchain type (e.g., bitcoin, litecoin)
  • name - The wallet name

Response

{
  "success": true,
  "reconciliation": {
    "blockchain": "bitcoin",
    "walletName": "btc_wallet_1",
    "primaryWalletBalance": 1.5,
    "aggregateInternalBalance": 1.5,
    "discrepancy": 0,
    "timestamp": "2025-03-13T12:00:00Z"
  },
  "messages": [
    {
      "type": "info",
      "code": "INFO_012",
      "message": "Reconciliation completed successfully",
      "data": {
        "blockchain": "bitcoin",
        "walletName": "btc_wallet_1",
        "discrepancy": 0
      },
      "timestamp": "2025-03-13T12:00:00Z"
    }
  ]
}

Merchant Fee Endpoints

These endpoints are available when using the merchant fee extension.

Configure Fee Structure

POST /api/fee-config

Configure the fee structure for merchant transactions.

Request Body

{
  "merchantWalletId": "internal_wallet_merchant",
  "feePercentage": 2.5,
  "minFee": 0.0001,
  "maxFee": 0.01,
  "feeCollectionWalletId": "internal_wallet_fees"
}

Response

{
  "success": true,
  "feeConfig": {
    "merchantWalletId": "internal_wallet_merchant",
    "feePercentage": 2.5,
    "minFee": 0.0001,
    "maxFee": 0.01,
    "feeCollectionWalletId": "internal_wallet_fees"
  }
}

Process Merchant Transaction

POST /api/transactions/merchant

Process a merchant transaction with automatic fee calculation and distribution.

Request Body

{
  "customerWalletId": "internal_wallet_customer",
  "merchantWalletId": "internal_wallet_merchant",
  "amount": 0.5,
  "memo": "Payment for services",
  "metadata": {
    "orderId": "order_123",
    "productId": "product_456"
  }
}

Response

{
  "success": true,
  "transaction": {
    "id": "tx_123",
    "customerWalletId": "internal_wallet_customer",
    "merchantWalletId": "internal_wallet_merchant",
    "amount": 0.5,
    "fee": 0.0125,
    "netAmount": 0.4875,
    "memo": "Payment for services",
    "metadata": {
      "orderId": "order_123",
      "productId": "product_456"
    },
    "timestamp": "2025-03-13T12:00:00Z"
  }
}

Employee Payroll Endpoints

These endpoints are available when using the employee payroll extension.

Register Employee

POST /api/employees

Register a new employee with the payroll system.

Request Body

{
  "employeeId": "emp_123",
  "name": "John Doe",
  "internalWalletId": "internal_wallet_emp_123",
  "salary": 0.5,
  "paymentFrequency": "monthly",
  "metadata": {
    "department": "Engineering",
    "position": "Software Developer"
  }
}

Response

{
  "success": true,
  "employee": {
    "employeeId": "emp_123",
    "name": "John Doe",
    "internalWalletId": "internal_wallet_emp_123",
    "salary": 0.5,
    "paymentFrequency": "monthly",
    "metadata": {
      "department": "Engineering",
      "position": "Software Developer"
    },
    "createdAt": "2025-03-13T12:00:00Z"
  }
}

Process Payroll

POST /api/payroll/process

Process payroll for all registered employees or a specific employee.

Request Body

{
  "employeeId": "emp_123",  // Optional, if not provided, process for all employees
  "payrollDate": "2025-03-31",
  "memo": "March 2025 Salary"
}

Response

{
  "success": true,
  "payroll": {
    "id": "payroll_123",
    "date": "2025-03-31",
    "totalAmount": 0.5,
    "employeeCount": 1,
    "transactions": [
      {
        "employeeId": "emp_123",
        "name": "John Doe",
        "internalWalletId": "internal_wallet_emp_123",
        "amount": 0.5,
        "memo": "March 2025 Salary",
        "timestamp": "2025-03-13T12:00:00Z"
      }
    ]
  }
}

Error Handling

FractaLedger API uses a consistent error format across all endpoints. When an error occurs, the API returns a JSON response with an error message and code.

Error Response Format

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {
      // Additional error details (optional)
    }
  }
}

Common Error Codes

Code Description
AUTH_001 Authentication failed. Invalid credentials.
AUTH_002 JWT token expired.
AUTH_003 Insufficient permissions.
WALLET_001 Wallet not found.
WALLET_002 Invalid wallet address format.
INTERNAL_WALLET_001 Internal wallet not found.
INTERNAL_WALLET_002 Insufficient balance in internal wallet.
TX_001 Transaction failed to broadcast.
TX_002 Invalid transaction format.
CHAINCODE_001 Chaincode deployment failed.
CHAINCODE_002 Chaincode execution failed.
SERVER_001 Internal server error.