Transactions API

Transfer Tokens (v2)

Send XRGE or custom tokens to another address using client-side ML-DSA-65 signing.

POST /api/v2/transfer
Content-Type: application/json

Request Body

{
  "payload": {
    "to": "recipient-public-key-hex",
    "amount": 100.0,
    "token": "XRGE",
    "from": "sender-public-key-hex",
    "timestamp": 1706745600000,
    "nonce": "random-hex-string"
  },
  "signature": "ml-dsa65-signature-hex",
  "public_key": "sender-public-key-hex"
}

Fee: The transaction fee is enforced by the server; any client-supplied fee in the payload is ignored.

Security: Private keys never leave your application. The transaction is signed client-side using ML-DSA-65 and the server verifies the signature before processing.

Response

{
  "success": true,
  "txId": "abc123..."
}

Error Response

{
  "success": false,
  "error": "insufficient balance: have 50.0000 XRGE, need 100.1000 XRGE"
}

Get Transactions

Retrieve recent transactions.

GET /api/txs?limit=50&offset=0

Query Parameters

Response

Each item wraps the transaction with its block context. The wrapper fields are camelCase (txId, blockHeight, blockHash, blockTime); the nested tx (a TxV1) is snake_case.

{
  "txs": [
    {
      "txId": "abc123...",
      "blockHeight": 42,
      "blockHash": "xyz...",
      "blockTime": 1706745600000,
      "tx": {
        "version": 1,
        "tx_type": "transfer",
        "from_pub_key": "abc...",
        "nonce": 1234567890,
        "payload": {
          "to_pub_key_hex": "def...",
          "amount": 100
        },
        "fee": 0.1,
        "sig": "ghi..."
      }
    }
  ],
  "total": 150
}

Get Transaction by Hash

GET /api/tx/:hash

Response

txId, blockHeight, blockHash, and blockTime are top-level (not inside tx). The nested tx (a TxV1) is snake_case, and receipt carries the execution receipt when present.

{
  "success": true,
  "txId": "abc123...",
  "blockHeight": 42,
  "blockHash": "xyz...",
  "blockTime": 1706745600000,
  "tx": {
    "version": 1,
    "tx_type": "transfer",
    "from_pub_key": "abc...",
    "nonce": 1234567890,
    "payload": {
      "to_pub_key_hex": "def...",
      "amount": 100
    },
    "fee": 0.1,
    "sig": "ghi..."
  },
  "receipt": null
}

Get Transaction Receipt

GET /api/tx/:hash/receipt

Returns execution receipt for contract calls and other complex transactions.

Request Faucet (v2)

Get free testnet XRGE tokens.

POST /api/v2/faucet
Content-Type: application/json

Request Body

{
  "payload": {
    "from": "your-public-key-hex",
    "timestamp": 1706745600000,
    "nonce": "random-hex-string"
  },
  "signature": "your-signature-hex",
  "public_key": "your-public-key-hex"
}

Response

{
  "success": true,
  "amount": 1000,
  "txId": "abc123..."
}

Rate Limit

The faucet has additional rate limiting:

• 1 request per address per hour
• Whitelisted addresses bypass rate limits

Transaction Types