Skip to content

Blocks API

Endpoints for submitting new blocks and querying existing ones. Blocks are the fundamental unit of the block lattice -- each one represents a single operation on an account's chain.

Block Object

All block types share a common set of fields, with additional fields depending on the type:

Common Fields

Field Type Description
type string Block type: send, receive, claim, lease, lease_accept, lease_settle, multisig_open, multisig_update
account string Hex-encoded ed25519 public key of the account
previous string Hash of the previous block in this account's chain (zero hash for genesis)
balance string Account balance after this block (string-encoded integer)
asset string Asset name: XE or XUSD
representative string Hex-encoded public key of the account's chosen representative
timestamp integer Unix nanosecond timestamp
signature string Hex-encoded ed25519 signature of the block hash
hash string Hex-encoded SHA-256 hash of the block contents
pow_nonce integer Proof-of-work nonce satisfying the difficulty target
signatures array Multisig signatures (replaces signature for multisig accounts)
keyset object Multisig keyset for multisig_open / multisig_update blocks

Submit Send Block

POST /blocks/send

Creates a send block that debits the sender's balance and creates a pending entry for the recipient.

Request Body

{
  "account": "a1b2c3d4...",
  "previous": "f2a3b4c5...",
  "balance": "900000",
  "destination": "e5f6a7b8...",
  "amount": "100000",
  "asset": "XE",
  "representative": "d4e5f6a7...",
  "timestamp": 1709500060000000000,
  "signature": "c1d2e3f4...",
  "hash": "a5b6c7d8...",
  "pow_nonce": 67890
}
Field Type Description
destination string Hex-encoded public key of the recipient
amount string Amount to send (string-encoded integer)

Response

{
  "hash": "a5b6c7d8..."
}

Errors

Status Description
400 Invalid block (bad signature, insufficient balance, wrong previous, etc.)

Submit Receive Block

POST /blocks/receive

Creates a receive block that credits a pending send to the recipient's account.

Request Body

{
  "account": "e5f6a7b8...",
  "previous": "b1c2d3e4...",
  "balance": "100000",
  "source": "a5b6c7d8...",
  "asset": "XE",
  "representative": "d4e5f6a7...",
  "timestamp": 1709500120000000000,
  "signature": "d5e6f7a8...",
  "hash": "c8d9e0f1...",
  "pow_nonce": 11111
}
Field Type Description
source string Hash of the send block being received

Response

{
  "hash": "c8d9e0f1..."
}

Errors

Status Description
400 Invalid block (no matching pending send, bad signature, etc.)

Submit Claim Block

POST /blocks/claim

Creates a claim block that mints 100 XUSD from the testnet faucet. Rate limited to once per 24 hours per account.

Request Body

{
  "account": "a1b2c3d4...",
  "previous": "0000000000000000000000000000000000000000000000000000000000000000",
  "balance": "100",
  "asset": "XUSD",
  "representative": "d4e5f6a7...",
  "timestamp": 1709500000000000000,
  "signature": "b8c9d0e1...",
  "hash": "f2a3b4c5...",
  "pow_nonce": 12345
}

Response

{
  "hash": "f2a3b4c5..."
}

Submit Lease Block

POST /blocks/lease

Creates a lease block requesting compute resources from the network. This is a special send block that includes resource requirements.

Request Body

{
  "account": "a1b2c3d4...",
  "previous": "f2a3b4c5...",
  "balance": "400000",
  "destination": "e5f6a7b8...",
  "amount": "100000",
  "asset": "XUSD",
  "representative": "d4e5f6a7...",
  "timestamp": 1709500060000000000,
  "signature": "c1d2e3f4...",
  "hash": "a5b6c7d8...",
  "pow_nonce": 67890,
  "vcpus": 4,
  "memory_mb": 8192,
  "disk_gb": 100,
  "duration": 86400
}
Field Type Description
vcpus integer Number of virtual CPUs requested
memory_mb integer Memory in megabytes
disk_gb integer Disk space in gigabytes
duration integer Lease duration in seconds

Response

{
  "hash": "a5b6c7d8..."
}

See Compute Leasing for the full lease lifecycle.

Submit Lease Accept Block

POST /blocks/lease_accept

Provider accepts a lease request. Requires timekeeper attestations.

Request Body

{
  "account": "e5f6a7b8...",
  "previous": "b1c2d3e4...",
  "balance": "100000",
  "source": "a5b6c7d8...",
  "asset": "XUSD",
  "representative": "d4e5f6a7...",
  "timestamp": 1709500180000000000,
  "signature": "d5e6f7a8...",
  "hash": "c8d9e0f1...",
  "pow_nonce": 22222,
  "attestations": [
    {
      "public_key": "f1a2b3c4...",
      "timestamp": 1709500175000000000,
      "signature": "e6f7a8b9..."
    }
  ]
}
Field Type Description
attestations array Array of timekeeper attestations

Submit Lease Settle Block

POST /blocks/lease_settle

Settles a completed lease. Requires timekeeper attestations. Triggers emission rewards for the provider.

Request Body

Same structure as lease_accept, with attestations confirming the lease has been fulfilled.

Submit Multisig Open Block

POST /blocks/multisig_open

Opens a new multisig account with a hash-derived address and registers the keyset on the ledger.

Request Body

{
  "type": "multisig_open",
  "account": "<sha256-of-keyset>",
  "previous": "0",
  "balance": 0,
  "asset": "XE",
  "keyset": {
    "keys": ["<pubkey1>", "<pubkey2>", "<pubkey3>"],
    "threshold": 2
  },
  "signatures": [
    {"public_key": "<pubkey1>", "signature": "<sig1>"},
    {"public_key": "<pubkey2>", "signature": "<sig2>"}
  ],
  "hash": "...",
  "pow_nonce": 12345
}

Submit Multisig Update Block

POST /blocks/multisig_update

Rotates the keyset on an existing multisig account. Must be signed by the current (old) keyset's threshold.

Request Body

{
  "type": "multisig_update",
  "account": "<multisig-address>",
  "previous": "<frontier>",
  "balance": 0,
  "asset": "XE",
  "keyset": {
    "keys": ["<new_pubkey1>", "<new_pubkey2>", "<new_pubkey3>", "<new_pubkey4>"],
    "threshold": 3
  },
  "signatures": [...],
  "hash": "...",
  "pow_nonce": 12345
}

Get Account Keyset

GET /accounts/{address}/keyset

Returns the multisig keyset for an account. Returns 404 if the account is not a multisig account.

Response

{
  "keys": ["<pubkey1>", "<pubkey2>", "<pubkey3>"],
  "threshold": 2
}

Get Block by Hash

GET /blocks/{hash}

Returns a single block by its hash.

Path Parameters

Parameter Type Description
hash string Hex-encoded block hash

Response

Returns a Block object (see Common Fields above, plus type-specific fields).

Errors

Status Description
404 Block not found

Example

curl http://localhost:8080/blocks/a5b6c7d8...

Get Recent Blocks

GET /blocks/recent

Returns recently processed blocks across all accounts.

Query Parameters

Parameter Type Default Description
limit integer 20 Maximum number of blocks to return

Response

Returns an array of Block objects, ordered newest first.

Example

curl http://localhost:8080/blocks/recent?limit=50

Compute Proof of Work

POST /pow

Computes a proof-of-work nonce for a given block hash. This is a convenience endpoint -- clients can also compute PoW locally.

Request Body

{
  "hash": "a5b6c7d8..."
}
Field Type Description
hash string Hex-encoded block hash to compute PoW for

Response

{
  "nonce": 67890
}

PoW details

XE uses blake2b with an 8-byte truncated digest for proof of work. The nonce must produce a hash below the network's difficulty target. See Proof of Work for the algorithm details.