AVEL MCP server

agent-interchange

SDK Python per AVEL (Agent Verification Layer) — verifica identità/reputazione di chi paga e chi riceve, su qualunque metodo di pagamento, senza mai custodire denaro. Il server è closed-source; questo pacchetto è lo strato client, pensato per essere pubblico e riusabile (licenza MIT). Standalone — nessuna dipendenza dal codice del server, solo httpx, eth-account e l'URL di un'istanza raggiungibile (https://aisrail.fly.dev).

<!-- mcp-name: io.github.Ensi81/avel -->

Install

pip install -e .

Uso

from agent_interchange import InterchangeClient

client = InterchangeClient("https://aisrail.fly.dev")
result = client.verify(
    payer_address=agent_a_address,
    payee_id="merchant-42",
    amount=25.0,
    currency="EUR",
    private_key=agent_a_private_key,
    fee_payment_method_id="pm_...",   # con cosa si paga LA VERIFICA
)

Il pagamento fra i due agenti non passa da qui. Questa chiamata dice soltanto se è sicuro procedere; poi l'agente paga sul rail che già usa. Noi incassiamo solo la provvigione per il controllo eseguito (1% dell'importo verificato, minimo 0,50 su carta) — dovuta anche su un verdetto DENIED, se la firma di chi chiama è comunque valida: è il prezzo del controllo, non dell'esito.

Tre esiti possibili:

private_key è la chiave EVM dell'agente (mai la nostra). Il primo uso autenticato lega quell'identità all'indirizzo che firma (trust-on-first-use): ogni chiamata successiva deve firmare con la STESSA chiave. Nessuna registrazione preventiva.

verify() usa protocol="native". Se l'agente sta già pagando con x402, AP2 o MPP non serve una seconda firma: si manda la prova che ha già prodotto per il pagamento — un esempio per ciascun protocollo è in scripts/protocoladaptersdemo.py.

Verifica simmetrica di B

Se il venditore (B) dichiara un indirizzo (payeeaddress), deve anche provare di controllarlo — altrimenti il verdetto è negato. La firma va calcolata da B (o da chi negozia per suo conto) su buildcounterpartymessage(payeraddress, payeeid, amount, currency, nonce) e passata come payeesignature:

from agent_interchange.client import build_counterparty_message

message = build_counterparty_message(payer_address, payee_id, amount, currency, nonce)
payee_signature = "0x" + Account.sign_message(encode_defunct(text=message), private_key=b_private_key).signature.hex()

result = client.verify(
    payer_address=a_address, payee_id="merchant-42", amount=25.0, currency="EUR",
    private_key=a_private_key, nonce=nonce,
    payee_address=b_address, payee_signature=payee_signature,
)

Modello B-driven (protocollo challenge)

Più vicino a come funzionano davvero x402/MPP: è il venditore (B) a fissare prezzo e termini e a firmarli per primo, l'acquirente (A) li accetta firmando lo stesso testo.

# Lato B — nessuna chiamata di rete, va consegnato ad A fuori banda
challenge = client.issue_challenge(
    payee_address=b_address, payee_id="merchant-42", amount=25.0, currency="EUR",
    private_key=b_private_key, ttl_seconds=600,
)

# Lato A — accetta il challenge e chiede il verdetto in un colpo solo
result = client.verify_challenge(
    challenge, payer_address=a_address, private_key=a_private_key,
    fee_payment_method_id="pm_...",   # o fee_method="x402" per pagare in stablecoin
)

Shortened. The full README is on GitHub.