API Reference

xAI Blockchain API

Niêm phong & xác minh tính toàn vẹn dữ liệu on-chain

xAI Blockchain cung cấp hai endpoint đơn giản để niêm phong dấu vân tay (fingerprint) dữ liệu lên sổ cái và xác minh tính toàn vẹn về sau. Dữ liệu được chuẩn hóa (canonical JSON) rồi băm keccak256 trước khi ghi on-chain — chỉ dấu vân tay được lưu, không lưu dữ liệu gốc.

Base URL

https://blockchain.xai.io.vn

Xác thực

Sandbox công khai chạy chế độ `mock` (mô phỏng tx/hash, không cần ví). Bản on-chain ký bằng khóa relayer lưu trong Cloudflare secret — không có khóa nào ở phía client. Khuyến nghị rate limit ~5 req/phút/IP.

Sổ cái

POST /api/anchor

Niêm phong dấu vân tay dữ liệu lên sổ cái

Xác thực: Không (sandbox công khai)

Tham số (body)

Trường	Kiểu	Mô tả
`scenario`*	`'e_invoice' \| 'fund_disbursal' \| 'kyc_profile'`	Loại kịch bản nghiệp vụ
`payloadId`*	`string`	Mã định danh nghiệp vụ, vd `INV-2026-001`
`dataFields`*	`object`	Cặp khóa-giá trị dữ liệu cần niêm phong

Ví dụ yêu cầu

curl -X POST 'https://blockchain.xai.io.vn/api/anchor' \
  -H 'Content-Type: application/json' \
  -d '{
    "scenario": "e_invoice",
    "payloadId": "INV-2026-001",
    "dataFields": { "taxId": "0312345678", "amount": 500000000, "issuedAt": "2026-05-30" }
  }'

const res = await fetch('https://blockchain.xai.io.vn/api/anchor', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    scenario: 'e_invoice',
    payloadId: 'INV-2026-001',
    dataFields: { taxId: '0312345678', amount: 500_000_000, issuedAt: '2026-05-30' },
  }),
});
const { dataHash, explorerUrl } = await res.json();

Phản hồi mẫu

{
  "success": true,
  "mode": "mock",
  "dataHash": "0x9af1…c20b",
  "transactionHash": "0x4e8d…7a31",
  "blockNumber": 14283910,
  "timestamp": 1769990400,
  "scenario": "e_invoice",
  "payloadId": "INV-2026-001",
  "explorerUrl": "https://sepolia.basescan.org/tx/0x4e8d…7a31"
}

Mã lỗi

`400`	Dữ liệu không hợp lệ
`409`	Dấu vân tay đã được niêm phong trước đó

POST /api/verify

Xác minh dữ liệu có khớp bản đã niêm phong

Xác thực: Không (sandbox công khai)

Tham số (body)

Trường	Kiểu	Mô tả
`dataFields`*	`object`	Dữ liệu cần kiểm chứng (băm lại & so khớp)

Ví dụ yêu cầu

curl -X POST 'https://blockchain.xai.io.vn/api/verify' \
  -H 'Content-Type: application/json' \
  -d '{ "dataFields": { "taxId": "0312345678", "amount": 500000000, "issuedAt": "2026-05-30" } }'

Phản hồi mẫu

{
  "success": true,
  "mode": "mock",
  "dataHash": "0x9af1…c20b",
  "onChain": true,
  "payloadId": "INV-2026-001",
  "timestamp": 1769990400,
  "anchoredBy": "0x71C…e3F2"
}

Smart contract

xAISandboxRegistry.sol

Hợp đồng đăng ký (EVM, Base Sepolia) — 3 hàm công khai

Xác thực: Ký bởi relayer (on-chain mode)

Giao diện

// Solidity — xAISandboxRegistry
function anchorData(bytes32 _dataHash, string _payloadId) external; // ghi, emit DataAnchored
function verifyData(bytes32 _dataHash)
  external view returns (bytes32, string, uint256, address);        // đọc bản ghi
function isAnchored(bytes32 _dataHash) external view returns (bool); // kiểm tra nhanh