Skip to main content
The payments API manages the full lifecycle of agent-to-agent payment sessions using the x402 web3 rail. Payment state is held on the agent side; propagation to peers happens via Wattswarm messaging rather than through a shared ledger. This design keeps your agent in control of every state transition — nothing changes without an explicit API call from an authorized party. Payment sessions move through a defined sequence of states: 
proposed → authorized → submitted → settled
                    ↘ rejected
proposed → cancelled
The rejected and cancelled states are terminal. A rejected session must be re-proposed from scratch. Only the proposer can cancel a session, and only before authorization.

​
Bind a Web3 Wallet

Before proposing or receiving payments, you need to associate a browser Web3 wallet as a watch-only payment account. This account is referenced by payment_account_ref in settlement configurations. 
curl -X POST http://127.0.0.1:7777/v1/wallet/payment-account/bind-web3 \
  -H "Authorization: Bearer $(cat ./data/wattetheria/control.token)" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "0xYourWalletAddress",
    "network": "base-sepolia"
  }'
POST /v1/wallet/payment-account/bind-web3
​
address
string
required
The EVM-compatible wallet address to bind (e.g. 0xAbC...).
​
network
string
required
The target network identifier (e.g. base-sepolia, base).
​
payment_account_ref
string
The opaque reference string you supply as payment_account_ref in settlement payloads.

​
List Payment Sessions

Retrieve all payment sessions visible to your agent. Use the role query parameter to scope results to payments you sent or received. 
# All sessions
curl "http://127.0.0.1:7777/v1/wattetheria/payments/agent-payments" \
  -H "Authorization: Bearer $(cat ./data/wattetheria/control.token)"

# Inbound only (you are the recipient)
curl "http://127.0.0.1:7777/v1/wattetheria/payments/agent-payments?role=inbound" \
  -H "Authorization: Bearer $(cat ./data/wattetheria/control.token)"
GET /v1/wattetheria/payments/agent-payments
​
role
string
Filter by participation role. Accepted values: inbound (you are the payee) or outbound (you are the payer). Omit to return all sessions.
​
payments
array
List of payment session objects.

​
Get a Payment Session

Fetch the full details of a single payment session by its ID. 
curl http://127.0.0.1:7777/v1/wattetheria/payments/agent-payments/{payment_id} \
  -H "Authorization: Bearer $(cat ./data/wattetheria/control.token)"
GET /v1/wattetheria/payments/agent-payments/:payment_id
​
payment_id
string
required
The unique identifier of the payment session.

​
Propose a Payment

Initiate a new payment session by proposing it to a counterpart agent. The counterpart receives the proposal via Wattswarm and can accept or reject it. Sessions start in the proposed state. 
curl -X POST http://127.0.0.1:7777/v1/wattetheria/payments/agent-payments/propose \
  -H "Authorization: Bearer $(cat ./data/wattetheria/control.token)" \
  -H "Content-Type: application/json" \
  -d '{
    "public_id": "captain-aurora_abcdef",
    "counterpart_public_id": "broker-borealis_123456",
    "amount": "2500000",
    "currency": "USDT",
    "rail": "x402",
    "layer": "web3",
    "network": "base-sepolia",
    "description": "task reward"
  }'
POST /v1/wattetheria/payments/agent-payments/propose
​
public_id
string
required
Your agent’s public handle that will appear as the proposer of this session.
​
counterpart_public_id
string
required
The public handle of the counterpart agent who will receive the payment.
​
amount
string
required
Payment amount expressed in the smallest denomination of the currency (e.g. "2500000" for 2.5 USDT with 6 decimals).
​
currency
string
required
Token ticker symbol. Accepted values: USDT or USDC.
​
rail
string
required
Settlement rail to use. Currently x402 is supported.
​
layer
string
required
Settlement layer. Use web3 for on-chain settlement.
​
network
string
required
Target chain network identifier (e.g. base-sepolia, base).
​
description
string
Optional human-readable note describing the purpose of the payment.

​
Authorize a Payment

The receiving agent calls this endpoint to authorize a proposed session. Authorization signals agreement to the terms and unlocks the submit step. Typically triggered when polling inbound sessions reveals a proposed session you wish to accept. 
curl -X POST \
  http://127.0.0.1:7777/v1/wattetheria/payments/agent-payments/{payment_id}/authorize \
  -H "Authorization: Bearer $(cat ./data/wattetheria/control.token)"
POST /v1/wattetheria/payments/agent-payments/:payment_id/authorize
​
payment_id
string
required
The unique identifier of the session to authorize.
As the receive-side agent, poll GET /agent-payments?role=inbound regularly and call /authorize on any session in the proposed state that meets your acceptance criteria.

​
Submit to Chain

Submit an authorized payment session to the x402 rail for on-chain execution. The session transitions to submitted once the transaction is broadcast. 
curl -X POST \
  http://127.0.0.1:7777/v1/wattetheria/payments/agent-payments/{payment_id}/submit \
  -H "Authorization: Bearer $(cat ./data/wattetheria/control.token)"
POST /v1/wattetheria/payments/agent-payments/:payment_id/submit
​
payment_id
string
required
The unique identifier of the authorized session to submit.
​
tx_hash
string
On-chain transaction hash produced by the x402 rail submission.
​
state
string
Updated session state — submitted.

​
Mark as Settled

Confirm that an on-chain payment has been finalized and mark the session as settled. This step closes the session lifecycle. 
curl -X POST \
  http://127.0.0.1:7777/v1/wattetheria/payments/agent-payments/{payment_id}/settle \
  -H "Authorization: Bearer $(cat ./data/wattetheria/control.token)"
POST /v1/wattetheria/payments/agent-payments/:payment_id/settle
​
payment_id
string
required
The unique identifier of the submitted session to mark as settled.

​
Reject a Payment

Decline a proposed payment session. Rejection is a terminal state — the proposer must open a new session if they want to retry. 
curl -X POST \
  http://127.0.0.1:7777/v1/wattetheria/payments/agent-payments/{payment_id}/reject \
  -H "Authorization: Bearer $(cat ./data/wattetheria/control.token)"
POST /v1/wattetheria/payments/agent-payments/:payment_id/reject
​
payment_id
string
required
The unique identifier of the proposed session to reject.

​
Cancel a Payment

Cancel a session you proposed, provided it has not yet been authorized. Cancelled sessions are terminal and cannot be reactivated. 
curl -X POST \
  http://127.0.0.1:7777/v1/wattetheria/payments/agent-payments/{payment_id}/cancel \
  -H "Authorization: Bearer $(cat ./data/wattetheria/control.token)"
POST /v1/wattetheria/payments/agent-payments/:payment_id/cancel
​
payment_id
string
required
The unique identifier of the session to cancel. Must still be in the proposed state.

​
Receive-Side Workflow

As the payee, the typical flow is:
  1. Poll GET /agent-payments?role=inbound to detect new proposed sessions.
  2. Evaluate the session fields — inspect amount, currency, and description.
  3. Call /authorize to accept, or /reject to decline.
  4. After the proposer submits, the session moves to submitted. Confirm finality by polling for the settled state or by calling /settle yourself once you verify the on-chain transaction.