# Amadeus Protocol RPC API Endpoints: Complete Reference for Node Integration

> Explore Amadeus Protocol RPC API endpoints for seamless node integration. Discover 40+ endpoints for chain queries, transactions, and more.

- Repository: [Amadeus Protocol/node](https://github.com/amadeusprotocol/node)
- Tags: api-reference
- Published: 2026-08-20

---

**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`](https://github.com/amadeusprotocol/node/blob/main/ex/config/runtime.exs) at line 42 for the configuration logic:

```elixir

# 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`](https://github.com/amadeusprotocol/node/blob/main/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`](https://github.com/amadeusprotocol/node/blob/main/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`](https://github.com/amadeusprotocol/node/blob/main/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.

## Contract-Related Endpoints

Smart contract interaction is a core capability. Lines 42-74 in [`multiserver.ex`](https://github.com/amadeusprotocol/node/blob/main/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

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

```

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

### Check Wallet Balance

```bash

# 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

```bash

# 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

```bash

# 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

```bash
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`](https://github.com/amadeusprotocol/node/blob/main/ex/lib/http/multiserver.ex) | Central HTTP router defining all RPC endpoints |
| [`ex/config/runtime.exs`](https://github.com/amadeusprotocol/node/blob/main/ex/config/runtime.exs) | `:rpc_url` configuration and environment overrides |
| [`ex/lib/api/rpc_api.ex`](https://github.com/amadeusprotocol/node/blob/main/ex/lib/api/rpc_api.ex) | Internal client wrapper for cross-node RPC calls |
| [`ex/lib/api/api_proof.ex`](https://github.com/amadeusprotocol/node/blob/main/ex/lib/api/api_proof.ex) | Merkle proof generation implementation |
| [`DOCS.md`](https://github.com/amadeusprotocol/node/blob/main/DOCS.md) | Public RPC URL reference for testnet and mainnet |

## Summary

- **Amadeus Protocol RPC endpoints** are defined in [`ex/lib/http/multiserver.ex`](https://github.com/amadeusprotocol/node/blob/main/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`](https://github.com/amadeusprotocol/node/blob/main/runtime.exs) configuration reads this variable, defaulting to `https://mainnet-rpc.ama.one`. Testnet URLs are documented in [`DOCS.md`](https://github.com/amadeusprotocol/node/blob/main/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.