api-reference

Amadeus Protocol RPC API Endpoints: Complete Reference for Node Integration

August 20, 2026 amadeusprotocol/node ↗

The Amadeus Protocol node exposes a REST-style HTTP API and WebSocket RPC interface with 40+ endpoints for chain queries, transactions, contracts, proofs, and peer discovery.

The Amadeus Protocol is a layer-1 blockchain built in Elixir that provides developers with extensive RPC capabilities for building wallets, explorers, and decentralized applications. This guide documents every public RPC endpoint available in the reference node implementation, with source-accurate details from the official repository.

Base URL Configuration

All RPC endpoints share a configurable base URL defined by the :rpc_url application setting.

The default mainnet endpoint is https://mainnet-rpc.ama.one. You can override this via the RPC_URL environment variable — see ex/config/runtime.exs at line 42 for the configuration logic:


# From runtime.exs

config :ama, :rpc_url, System.get_env("RPC_URL") || "https://mainnet-rpc.ama.one"

This design allows seamless switching between mainnet, testnet, and private network deployments without code changes.

WebSocket RPC Endpoints

Real-time, bidirectional communication is handled through dedicated WebSocket paths. In ex/lib/http/multiserver.ex lines 52-54, the router mounts these handlers:

/ws/rpc — Primary WebSocket RPC channel for persistent connections
/ws/rpc/test — Health-check endpoint returning a static HTML page

Use the WebSocket interface for streaming updates and low-latency operations that don't fit the request-response model.

Health and Metrics Endpoints

Monitor node health and extract operational data through these Prometheus-compatible endpoints. Lines 61-70 in multiserver.ex define:

Endpoint	Method	Purpose
`/health`	GET	Liveness probe for load balancers
`/metrics`	GET	Full Prometheus metrics export
`/metrics/stats`	GET	Condensed statistics summary
`/metrics/kpi`	GET	Key performance indicators
`/metrics/validators`	GET	Validator-specific operational metrics

These endpoints are essential for production deployments requiring observability and alerting.

Peer Discovery Endpoints

The Amadeus Protocol uses ANR (Amadeus Network Routing) for peer coordination. Lines 72-89 in multiserver.ex expose:

/api/peer/anr/:pk — Retrieve a single ANR record by public key
/api/peer/anr_validators — List ANR records filtered to validators only
/api/peer/anr — Complete ANR record listing
/api/peer/nodes — All known peer nodes in the DHT
/api/peer/trainers and /api/peer/validators** — Role-specific peer lists
/api/peer/removed_trainers — Historical record of departed trainers

These endpoints support network topology analysis and bootstrapping new nodes.

Chain Information Endpoints

Query blockchain state at various granularities. Lines 92-104 implement:

/api/chain/stats — Global chain statistics
/api/chain/kpi — Chain-level KPI values
/api/chain/tip — Latest block (tip entry)
/api/chain/hash/:hash — Entry lookup by hash; supports filter_on_function query parameter
/api/chain/height/:height — Entry at specific block height
/api/chain/height_with_txs/:height — Entry with full transaction inclusion data
/api/chain/tx/:txid — Detailed transaction information

The filter_on_function parameter for hash queries enables efficient filtering of contract-related entries.

Epoch Services Endpoints

Amadeus Protocol organizes consensus into epochs with specialized query endpoints. Lines 126-138 define:

/api/epoch/score/:pk? — Global or per-public-key epoch scores
/api/epoch/get_emission_address/:pk — Emission address lookup
/api/epoch/sol_in_epoch/:sol_epoch/:sol_hash — SOL (Proof of Solvency) proof data for cross-epoch verification

Epoch queries are critical for validators participating in consensus and reward distribution.

Smart contract interaction is a core capability. Lines 42-74 in multiserver.ex expose:

/api/contract/validate (POST) — Validate WASM contract binary before deployment
/api/contract/get (POST) — Retrieve raw contract state by key
/api/contract/get_prefix (POST) — Prefix search with 8-byte minimum
/api/contract/view (POST) — Execute view function with binary vecpak payload
/api/contract/view/:contract/:function (GET) — URL-encoded view execution
/api/contract/richlist (GET) — Top contract holders

The POST view endpoint accepts binary vecpak-encoded arguments, while the GET variant uses URL encoding for simpler clients.

Transaction Submission Endpoints

Submit transactions with flexible confirmation strategies. Lines 451-474 implement:

/api/tx/submit (POST) — Submit raw transaction (binary or Base58)
/api/tx/submit_and_wait (POST) — Submit and await finalization
/api/tx/submit/:tx_packed (GET) — URL-encoded Base58 submission
/api/tx/submit_and_wait/:tx_packed (GET) — URL-encoded with wait

The finalized query parameter on submit_and_wait controls whether to wait for full finalization or optimistic inclusion.

State Synchronization and Proof Endpoints

Light clients and bridges rely on cryptographic proofs. Lines 76-99 provide:

/api/sync/contractstate — Contract state snapshot download (requires statepeerdownload feature)
/api/proof/validators/:entry_hash — Merkle proof for validator set
/api/proof/contractstate/:key and /:key/:value — Single or paired key proofs
/api/proof/contractstate (POST) — Binary vecpak proof requests

These endpoints enable trust-minimized verification without full node synchronization.

Wallet Query Endpoints

Asset and address inspection for wallet applications. Lines 332-346 expose:

/api/wallet/balance/:pk — Balance for default AMA token
/api/wallet/balance/:pk/:symbol — Specific asset balance
/api/wallet/balance_all/:pk — All asset balances in single query
/api/wallet/malicious_address — Known-malicious address list for client-side filtering

The balance endpoints support both simplified and comprehensive asset tracking.

Testnet-Only UPoW Endpoints

Universal Proof of Work (UPoW) testing utilities. Lines 104-147 (testnet builds only):

/api/upow/seed — Generate UPoW seed
/api/upow/seed_with_matrix_a_b — Seed with pre-computed matrix
/api/upow/validate/:sol (GET) — Solution verification
/api/upow/validate (POST) — Solution verification with body payload

These endpoints are absent from mainnet builds — attempting to call them on production nodes returns 404.

Practical Code Examples

Query Chain Statistics

curl https://mainnet-rpc.ama.one/api/chain/stats

Returns JSON with height, epoch, total_supply, and network parameters.

Check Wallet Balance


# Default AMA token

curl https://mainnet-rpc.ama.one/api/wallet/balance/7XnWYc4RT6ujKhVb8MgWJfks9ECR8iQsPjZwzpJM1UFJWhQhazsSXAZP42E1o37qGR

# Specific token symbol

curl https://mainnet-rpc.ama.one/api/wallet/balance/7XnWYc4RT6ujKhVb8MgWJfks9ECR8iQsPjZwzpJM1UFJWhQhazsSXAZP42E1o37qGR/CUSTOM

Submit Transaction with Finalization Wait


# Encode binary transaction to Base58 first

TX_B58=$(base58 < signed_tx.bin)

curl -X POST "https://mainnet-rpc.ama.one/api/tx/submit_and_wait/${TX_B58}?finalized=true"

Response includes receipt only after chain finalization.

Execute Contract View Function


# URL-encoded contract call

curl "https://mainnet-rpc.ama.one/api/contract/view/3yZ9d3CV7qWQZL9jD7G5r8vK9mN2X4Y5aBcDeFgHiJkLm/ balance_of?pk=7XnWYc4RT6ujKhVb8MgWJfks9ECR8iQsPjZwzpJM1UFJWhQhazsSXAZP42E1o37qGR"

JSON response contains success boolean, result bytes, and execution logs.

Validate WASM Contract

curl -X POST -H "Content-Type: application/octet-stream" \
     --data-binary @contract.wasm \
     https://mainnet-rpc.ama.one/api/contract/validate

Valid contracts return {"error": "ok", "result": "valid"}.

Source File Reference

File	Role
`ex/lib/http/multiserver.ex`	Central HTTP router defining all RPC endpoints
`ex/config/runtime.exs`	`:rpc_url` configuration and environment overrides
`ex/lib/api/rpc_api.ex`	Internal client wrapper for cross-node RPC calls
`ex/lib/api/api_proof.ex`	Merkle proof generation implementation
`DOCS.md`	Public RPC URL reference for testnet and mainnet

Summary

Amadeus Protocol RPC endpoints are defined in ex/lib/http/multiserver.ex with 40+ paths across 11 functional categories
WebSocket RPC at /ws/rpc provides real-time bidirectional communication
Base URL defaults to https://mainnet-rpc.ama.one via :rpc_url configuration
Contract endpoints support both binary vecpak (POST) and URL-encoded (GET) parameter passing
Proof endpoints enable light client verification of validator sets and contract state
Testnet-only UPoW endpoints are conditionally compiled and absent from production builds

Frequently Asked Questions

How do I switch from mainnet to testnet RPC endpoints?

Set the RPC_URL environment variable before starting your node or client. The runtime.exs configuration reads this variable, defaulting to https://mainnet-rpc.ama.one. Testnet URLs are documented in DOCS.md within the repository.

What is the difference between `/api/tx/submit` and `/api/tx/submit_and_wait`?

**submit** returns immediately with acceptance status, while **submit_and_wait** blocks until the transaction reaches the requested confirmation depth. Use ?finalized=true` to wait for full finalization rather than mere inclusion. Both support POST (binary/Base58 body) and GET (URL-encoded payload) variants.

Why does my contract view call return binary data instead of JSON?

The result field contains raw vecpak-encoded bytes by design. Deserialize using the Amadeus SDK or reference the vecpak specification. The logs field provides human-readable execution trace information in JSON format.

Which endpoints require special node configuration?

The /api/sync/contractstate endpoint only functions when the node is built with statepeerdownload enabled. UPoW endpoints are exclusively available in testnet builds. Check your node's compiled features before relying on these capabilities.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:

curl -s "https://instagit.com/install.md"

Add to your MCP client configuration:

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}

Ask your agent:

"Use Instagit MCP to understand how amadeusprotocol/node works."

Works with

Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →