Glasshim Blockchain API

Overview

The Glasshim Blockchain is a decentralized local ledger synchronized over the Glasshim P2P mesh. There is no central server — each device maintains signed transaction records and wallet balances.

Network Fees (1%)

Every user transfer and API transfer deducts a 1% network fee from the gross amount. The fee is credited to the admin treasury wallet (Himal Poudel).

Fee-exempt: admin grants, admin balance adjustments, mining credits.

Preview fees before sending with GET /quote.

Authentication

All REST requests require:

1. An active admin session on the admin device (password + 2FA logged in)
2. Header X-Glasshim-Api-Key: <your-api-key>

Generate the API key from Admin Dashboard → Blockchain API → Copy API Key.

curl "http://192.168.1.50:8765/api/v1/blockchain/balance?meshId=abc12345" \
  -H "X-Glasshim-Api-Key: gh_your_api_key_here"

REST Endpoints

Base path: /api/v1/blockchain/

GET /api/v1/blockchain/docs

Returns machine-readable JSON schema for all endpoints, fee policy, and security notes.

{
  "name": "Glasshim Blockchain API",
  "version": "2.0",
  "baseUrl": "http://<admin-device-ip>:8765",
  "feePolicy": { "rate": 0.01, "percent": "1%", "recipient": "Himal Poudel" },
  "endpoints": [ "..."]
}

GET /api/v1/blockchain/fees

Returns the current fee policy for API integrators and users.

{
  "feeRate": 0.01,
  "feePercent": "1%",
  "feeRecipient": "Himal Poudel",
  "adminMeshId": "abc12345",
  "notice": "All API transfers incur a 1% network fee...",
  "appliesTo": ["user_transfers", "api_transfers"],
  "exempt": ["admin_grants", "admin_adjustments", "mining_credits"]
}

GET /api/v1/blockchain/quote?amount={gross}

Preview transfer amounts before executing. Required query parameter: amount (gross Glasshim).

{
  "grossAmount": 100.0,
  "netAmount": 99.0,
  "feeAmount": 1.0,
  "feeRate": 0.01,
  "feeRecipient": "Himal Poudel",
  "adminMeshId": "abc12345",
  "notice": "A 1% Glasshim network fee applies..."
}

GET /api/v1/blockchain/balance?meshId={glasshimId}

Returns balance for a Glasshim ID on the admin device's local ledger.

{
  "meshId": "abc12345",
  "balance": 42.5,
  "coin": "Glasshim",
  "feeNotice": "A 1% Glasshim network fee applies..."
}

GET /api/v1/blockchain/transactions?meshId={id}&limit=50

Returns recent transactions including fee breakdown and privacy fields.

{
  "meshId": "abc12345",
  "feeNotice": "A 1% Glasshim network fee applies...",
  "transactions": [
    {
      "txId": "uuid",
      "fromMeshId": "abc12345",
      "toMeshId": "def67890",
      "amount": 10.0,
      "netAmount": 9.9,
      "feeAmount": 0.1,
      "type": "TRANSFER",
      "status": "CONFIRMED",
      "nonce": "uuid",
      "privacyToken": "a1b2c3d4...",
      "timestamp": 1735689600000
    }
  ]
}

GET /api/v1/blockchain/transaction/{txId}

Lookup a single transaction by ID. Status: PENDING, CONFIRMED, or FAILED.

{
  "transaction": {
    "txId": "uuid",
    "status": "CONFIRMED",
    "amount": 10.0,
    "netAmount": 9.9,
    "feeAmount": 0.1
  }
}

POST /api/v1/blockchain/transfer

Execute a signed P2P transfer from the admin wallet. 1% fee applies.

Request body (JSON):

{
  "toMeshId": "def67890",
  "amount": 100.0,
  "memo": "optional payment note"
}

Success response:

{
  "ok": true,
  "txId": "uuid",
  "grossAmount": 100.0,
  "netAmount": 99.0,
  "feeAmount": 1.0,
  "feeRate": 0.01,
  "feeRecipient": "Himal Poudel",
  "feeNotice": "A 1% Glasshim network fee applies...",
  "quote": { "...": "..." }
}

Memos are AES-GCM encrypted on the mesh when the recipient's public key is known.

POST /api/v1/blockchain/grant

Grant Glasshim from the admin pool (200M allocation). No network fee.

{
  "toMeshId": "def67890",
  "amount": 100.0,
  "memo": "partner allocation"
}

{
  "ok": true,
  "txId": "uuid",
  "amount": 100.0,
  "feeAmount": 0,
  "feeNotice": "Admin grants are fee-exempt"
}

POST /api/v1/blockchain/adjust

Admin balance correction. Positive = credit, negative = debit. No network fee.

{
  "toMeshId": "def67890",
  "amount": -2.5,
  "memo": "correction"
}

Mesh P2P Packets

All payloads are JSON inside MeshPacket.payload and broadcast device-to-device.

COIN_XFER — User transfer (v2)

{
  "tx_id": "uuid",
  "from_mesh_id": "abc12345",
  "to_mesh_id": "def67890",
  "from_public_key": "base64...",
  "gross_amount": 10.0,
  "net_amount": 9.9,
  "fee_amount": 0.1,
  "admin_mesh_id": "admin1234",
  "encrypted_memo": { "ciphertext": "...", "iv": "..." },
  "nonce": "uuid",
  "privacy_token": "a1b2c3d4e5f6...",
  "timestamp": 1735689600000,
  "signature": "base64-ecdsa..."
}

COIN_FEE — Admin treasury fee

{
  "tx_id": "uuid",
  "from_mesh_id": "abc12345",
  "from_public_key": "base64...",
  "admin_mesh_id": "admin1234",
  "fee_amount": 0.1,
  "nonce": "uuid",
  "timestamp": 1735689600000,
  "signature": "base64-ecdsa..."
}

COIN_ACK — Transfer acknowledgment (v2)

{
  "tx_id": "uuid",
  "from_mesh_id": "abc12345",
  "to_mesh_id": "def67890",
  "net_amount": 9.9,
  "fee_amount": 0.1,
  "nonce": "uuid",
  "timestamp": 1735689601000,
  "signature": "base64-ecdsa..."
}

ADMIN_GRANT — Admin pool grant

{
  "tx_id": "uuid",
  "admin_mesh_id": "admin1234",
  "to_mesh_id": "user5678",
  "admin_public_key": "base64...",
  "amount": 100.0,
  "memo": "promotion reward",
  "timestamp": 1735689600000,
  "signature": "base64-ecdsa..."
}

Canonical Signing Strings

All transfers are signed with ECDSA SHA256withECDSA. Verify signatures before crediting balances.

GLASSHIM_TRANSFER|v2|{tx_id}|{from}|{to}|{gross}|{net}|{fee}|{admin}|{nonce}|{privacy_token}|{timestamp}

GLASSHIM_FEE|v2|{tx_id}|{from}|{admin}|{fee}|{nonce}|{timestamp}

GLASSHIM_ACK|v2|{tx_id}|{from}|{to}|{net}|{fee}|{nonce}|{timestamp}

GLASSHIM_ADMIN_GRANT|{tx_id}|{admin_mesh_id}|{to_mesh_id}|{amount}|{timestamp}

Security & Privacy

• ECDSA signatures — every transfer, ACK, fee, and admin grant is signed
• ACK verification — sender verifies recipient signature before marking CONFIRMED
• Replay protection — unique tx_id + nonce per transfer
• Encrypted memo — AES-GCM via ECDH when recipient public key is known
• Privacy token — opaque SHA-256 reference; memo not exposed in plaintext on mesh
• Pending timeout — unconfirmed transfers auto-refund after 30 minutes
• Push notifications — sender, recipient, and admin notified of transfers and fees

Error Responses

{ "error": "Invalid API key", "feeNotice": "..." }

cURL Examples

Preview fee

curl "http://192.168.1.50:8765/api/v1/blockchain/quote?amount=100" \
  -H "X-Glasshim-Api-Key: gh_your_api_key_here"

Check balance

curl "http://192.168.1.50:8765/api/v1/blockchain/balance?meshId=abc12345" \
  -H "X-Glasshim-Api-Key: gh_your_api_key_here"

Transfer with 1% fee

curl -X POST "http://192.168.1.50:8765/api/v1/blockchain/transfer" \
  -H "Content-Type: application/json" \
  -H "X-Glasshim-Api-Key: gh_your_api_key_here" \
  -d '{"toMeshId":"abc12345","amount":100,"memo":"API payment"}'

Admin grant (fee-exempt)

curl -X POST "http://192.168.1.50:8765/api/v1/blockchain/grant" \
  -H "Content-Type: application/json" \
  -H "X-Glasshim-Api-Key: gh_your_api_key_here" \
  -d '{"toMeshId":"abc12345","amount":50,"memo":"Glasshim reward"}'

Token Supply