Skip to content

API Reference

All endpoints are served by the Wasichain gateway on a single HTTP port (default: http://localhost:8080).

Status

Method Path Description
GET /v1/status Unified node status including chain sync state and admission health.

Response:

{
  "node_id": "local",
  "height": 42,
  "epoch": 3,
  "sync_status": "synced",
  "validator_count": 4,
  "chain_online": true,
  "admission": {
    "online": true,
    "healthy": true,
    "queue_depth": 0,
    "vm_version": "wasmtime-43.0.0+abi-1.0.0+features-minimal-wasip2-v1"
  }
}

When a subsystem is unreachable, its fields will reflect that (e.g. chain_online: false with chain fields absent, or admission.online: false).

Transactions

Method Path Description
POST /v1/tx Submit a signed transaction. Body: JSON-serialized SignedTx. Returns { tx_hash, accepted, error? }.
GET /v1/tx/{hash} Look up a transaction receipt by hash. Returns 404 if not found.

Blocks

Method Path Description
GET /v1/block/{height}/txs All transaction receipts in a block at the given height. Returns { height, tx_count, transactions }.

Accounts

Method Path Description
GET /v1/account/{address} Account info: address, balance, nonce.

Code & Admission

Method Path Description
GET /v1/code/{id} Look up an on-chain code record by sequential code ID. Returns { code_id, code_hash, vm_version, status, blob_size }.
GET /v1/code/hash/{hash} Look up a code record by SHA-256 hash. Same response shape as above.
POST /v1/code Upload raw Wasm bytes for admission. Content-Type: application/wasm. Returns the code hash.
POST /v1/code/announce Announce a previously uploaded blob to trigger the admission pipeline.
GET /v1/code/{hash}/logs Compilation/admission logs for an uploaded blob.
GET /v1/healthz Admission subsystem health check.

Contracts

Method Path Description
GET /v1/contract/{address} Contract metadata: address, code_id, creator, label, init_height.
POST /v1/contract/{address}/query Execute a read-only query against a contract. Body: { msg: <bytes> }. Returns the query result.

Validators

Method Path Description
GET /v1/validator-set Current validator set: epoch, validators[] (each with pubkey, weight, stake).

Metrics

Method Path Description
GET /v1/metrics Prometheus-format metrics. Also available on the dedicated metrics port (default: 9100).

Error responses

All endpoints return standard HTTP status codes. Error bodies follow the shape:

{ "error": "description of what went wrong" }

Common codes:

  • 404 — resource not found (transaction, code, contract, block)
  • 400 — malformed request
  • 202 — transaction accepted into mempool (does not guarantee execution)
  • 500 — internal server error
  • 502 — gateway could not reach the backend service

Architecture note

The gateway (gatewayd) is a lightweight reverse proxy that aggregates two internal services:

  • chaind (default: 127.0.0.1:26657) — the chain node handling consensus, blocks, transactions, accounts, contracts, and validators.
  • admissiond (default: 127.0.0.1:8081) — the admission sidecar that validates and precompiles WASM contract code before it enters the chain.

The /v1/status endpoint merges responses from both services. All other requests are routed to the appropriate backend based on path.

For advanced use cases (debugging, direct access), the subsystems can be called directly on their respective ports. The gateway configuration (gateway.toml) controls the listen address and backend URLs.