Developer API and MCP

Developer

Fluxus exposes the shipped backend surface behind Phase 4: free REST reads, an authenticated send endpoint, an MCP tool layer for AI agents, and monetized machine-payment routes over HTTP 402.

Designed for backends, automations, and agent runtimes that need Tempo-native payments.

Architecture

REST API

Free read endpoints for balances, history, and .pay name resolution, plus one authenticated send route for production integrations.

MPP Gateway

Machine-to-machine endpoints monetize send, streaming, and scheduled payment flows with HTTP 402 pricing in pathUSD.

MCP Server

A compact nine-tool surface lets Claude Code style agents inspect accounts, initiate payments, and prepare Tempo-native intents.

REST API

The public REST layer is intentionally small: four free read routes and one authenticated write route for sending TIP-20 payments.

Method	Endpoint	Access	Notes
GET	/api/v1/balance/:address	Free	Returns balances for all supported Tempo stablecoins.
GET	/api/v1/resolve/:name	Free	Resolves a .pay name to a Tempo address.
GET	/api/v1/reverse/:address	Free	Performs reverse lookup for registered .pay names.
GET	/api/v1/history/:address	Free	Returns indexed activity with a recent-block fallback when needed.
POST	/api/v1/send	Bearer auth	Signs and submits a TIP-20 transfer with optional memo.

Auth: POST /api/v1/send expects an Authorization: Bearer <FLUXUS_API_KEY> header and signs with the configured sender wallet.

MCP server

Fluxus exposes a compact MCP surface tuned for agent workflows: read account state, resolve names, prepare requests, and trigger payment actions without surfacing unrelated app features.

Tool	Input	Returns
get_balance	address	Stablecoin balances for the requested account
resolve_name	name	.pay resolution result
reverse_lookup	address	Reverse name record for an address
get_history	address	Recent on-chain history for an account
send_payment	to, amount, token, memo?	Authenticated single transfer result
batch_send	recipients[].{to, amount, memo?}	Client-side batch payment orchestration
create_request	amount, token, memo?	Shareable payment request intent
start_stream	to, amount, duration_minutes	Streaming payment setup URL (no on-chain action)
create_scheduled	to, amount, delay_minutes, window_minutes	Scheduled payment setup URL (no on-chain action)

Claude Code JSON config

{
  "mcpServers": {
    "fluxus": {
      "command": "npx",
      "args": ["fluxus-mcp"],
      "env": {
        "FLUXUS_BASE_URL": "https://your-domain.com",
        "FLUXUS_API_KEY": "your-bearer-token"
      }
    }
  }
}

MPP

Machine Payments Protocol adds paid agent routes. Read endpoints stay free, while send and intent-creation endpoints challenge with HTTP 402 and settle in pathUSD.

Method	Endpoint	Price	Notes
GET	/api/mpp/balance/:address	Free	Machine-readable balance lookup for agent clients.
GET	/api/mpp/resolve/:name	Free	Machine-readable .pay resolution.
GET	/api/mpp/history/:address	Free	Machine-readable history lookup.
POST	/api/mpp/send	0.01 pathUSD	Paid direct send execution.
POST	/api/mpp/stream	0.02 pathUSD	Paid streaming setup intent.
POST	/api/mpp/scheduled	0.02 pathUSD	Paid scheduled payment setup intent.

HTTP 402 flow example

POST /api/mpp/send
→ 402 Payment Required
{
  "paymentMethod": "mpp-tempo-charge",
  "amount": "0.01",
  "currency": "pathUSD"
}

POST /api/mpp/send
(with completed MPP payment)
→ 200 OK
{
  "hash": "0x...",
  "paymentMethod": "mpp-tempo-charge"
}

Environment variables

Variable	Required	Notes
FLUXUS_API_KEY	Required for /api/v1/send	Bearer token checked before authenticated send execution.
FLUXUS_SENDER_PRIVATE_KEY	Required	Signing key used by authenticated send and MPP paid routes.
MPP_SECRET_KEY	Required for /api/mpp/*	Enables HTTP 402 challenge and receipt handling.
NEXT_PUBLIC_TEMPO_RPC_URL	Optional	Overrides the default Moderato RPC endpoint.

Network info

Chain ID: 42431
RPC: https://rpc.moderato.tempo.xyz
Explorer: https://explore.tempo.xyz
Settlement token: pathUSD (6 decimals)