AlgoVoi Gateway — MPP Grade D

Verify an on-chain payment transaction for the MPP adapter. The adapter submits the tx_id and network from the payer's credential; the gateway looks up the resource definition to get the expected amount and receiver, then delegates to the facilitator for on-chain confirmation. Returns a receipt JWT on success.

Verify an AP2 mandate credential submitted by a payer. The mandate dict must contain a ``signature`` field holding the JWT access token issued by POST /ap2/confirm. The gateway verifies the JWT signature, checks that the tenant_id claim matches the authenticated tenant, and confirms the token has not expired. Returns ``{"verified": true}`` on success.

Initiate an on-chain transfer from the tenant's custodial balance. Idempotent on ``reference``: submitting the same reference twice returns the original payout_id + tx_id without re-broadcasting to the chain. Supported networks (MVP): algorand_mainnet, voi_mainnet (USDC / aUSDC). currency must be USD (USDC peg assumed 1:1).

Explicit challenge pre-fetch for MPP agents that want to obtain a challenge token before building their payment transaction. Returns the same challenge object that GET /mpp/{resource_id} returns in its 401 body, allowing agents to pipeline challenge fetch → pay → proof submission without the round-trip to the resource endpoint.

Discovery probe + operator-level paid resource. No Authorization header → 402 + WWW-Authenticate: Payment challenge. Authorization: Payment <proof> → verify on-chain → 200 receipt. Payment goes to the AlgoVoi operator address (not a tenant). No DB session needed — facilitator verifies on-chain; receipt is logged.

Discovery probe + operator-level paid resource. No Authorization header → 402 + WWW-Authenticate: Payment challenge. Authorization: Payment <proof> → verify on-chain → 200 receipt. Payment goes to the AlgoVoi operator address (not a tenant). No DB session needed — facilitator verifies on-chain; receipt is logged.

Discovery probe + operator-level paid resource. No Authorization header → 402 + WWW-Authenticate: Payment challenge. Authorization: Payment <proof> → verify on-chain → 200 receipt. Payment goes to the AlgoVoi operator address (not a tenant). No DB session needed — facilitator verifies on-chain; receipt is logged.

Discovery probe + operator-level paid resource. No Authorization header → 402 + WWW-Authenticate: Payment challenge. Authorization: Payment <proof> → verify on-chain → 200 receipt. Payment goes to the AlgoVoi operator address (not a tenant). No DB session needed — facilitator verifies on-chain; receipt is logged.

Discovery probe + operator-level paid resource. No Authorization header → 402 + WWW-Authenticate: Payment challenge. Authorization: Payment <proof> → verify on-chain → 200 receipt. Payment goes to the AlgoVoi operator address (not a tenant). No DB session needed — facilitator verifies on-chain; receipt is logged.

IETF draft-httpauth-payment resource gate. No Authorization header → HTTP 401 + WWW-Authenticate: Payment challenge. Authorization: Payment <b64> → validate challenge echo → verify on-chain → HTTP 200. The x402 /protected/{resource_id} endpoint is completely unchanged.

MPP subscription gate (API key auth). No proof → 402 + intent="subscription" challenge with periodCount/periodUnit. Credential present → verify authority tx → create MppSubscription → return subscriptionId.

MPP subscription gate (API key auth). No proof → 402 + intent="subscription" challenge with periodCount/periodUnit. Credential present → verify authority tx → create MppSubscription → return subscriptionId.

Receive an IntentMandate. If user_authorization is present (SD-JWT-VC), verification is deferred to /pay where it binds to specific cart and payment hashes — at /intent stage we have nothing concrete to bind to. Per spec: if intent is not user-signed, user_cart_confirmation_required MUST be True (otherwise the agent could shop unilaterally without consent).

Returns the AP2 extensions this gateway supports. Used by AP2 agents to discover available payment methods (e.g. AlgoVoi crypto rails) before constructing a CartMandate.

Authenticated extended agent card. Returns the base card enriched with tenant-specific endpoint info.

Send a message to the AlgoVoi payment agent. The agent processes the task synchronously and returns the completed task within the same response. All three payment skills are supported: verify-payment, create-checkout, check-status. Input DataPart must include a 'skill' field identifying which skill to invoke.

Get the current state of a task by ID.

Cancel a task. Since AlgoVoi tasks complete synchronously, only tasks in 'submitted' or 'working' state can be cancelled. Completed/failed tasks return 409.

List recent tasks for this session. Returns tasks from the in-process store (TTL 10 minutes). In production, tasks complete within the send_message call so this endpoint is primarily for debugging.

Create a hosted checkout link for a specific fiat amount. The amount is converted to stablecoin (USDC / aUSDC) or native crypto using the tenant's configured network and the live FX rate. The returned `checkout_url` can be sent directly to the buyer.

Public page — single-use cancel link given to customer at signup. GET shows a confirmation page; POST commits the cancellation.

Cross-tenant. Returns every subscription where the wallet matches a customer row, regardless of which tenant owns that subscription.

Tenant-agnostic customer portal — connect wallet, see all subscriptions across every merchant who has billed that wallet. Embeds zero JS framework. Wallets: - EVM (Base, Tempo, ...): MetaMask injected provider + EIP-191 personal_sign - Solana: window.solana (Phantom) - Algorand / VOI: Pera, Defly, Lute (signData with "MX" prefix) - Stellar: Stellar Wallets Kit (Freighter, Albedo, xBull, Lobstr, Hana, Rabet) - Hedera: Hedera Wallet Connect (HashPack, Blade, Kabila) via Reown Security: pre-sale Comet third-pass review (2026-05-07, Task A) caught that the previous `replace('"', "")` sanitisation of the `chain` query parameter was insufficient — single quotes and semicolons fell through into a JS string literal under the legacy 'unsafe-inline' CSP applied to /recurr/portal, enabling reflected XSS via `?chain='; alert(1);//`. Replaced with a strict allowlist. The `wc_pid` reflection is also tightened to a 32-char-hex regex even though it sources from settings.

Create a Tier 2 standing authority for an existing subscription. Returns the server-recorded authority (status='pending') plus the chain-specific payload the customer's wallet signs to land the on-chain authorisation. The AlgoVoi widget consumes the payload; the customer signs the 6-action atomic group; AlgoVoi confirms the landing and a separate POST /confirm transitions to 'active'.

Mark an authority active after on-chain landing. The tenant calls this once they (or the AlgoVoi widget) has confirmed the customer's signed transaction group landed on-chain. ``on_chain_address`` carries the chain-specific identifier (e.g. ``app:<application_id>``).

Manually request a pull cycle. Returns the (unchanged) authority record. The actual chain-side pull submission is performed by the Sprint 1.5c cycle reaper (which this endpoint signals via setting ``next_cycle_due_at = now``). For 1.5b this endpoint validates the request shape and updates next_cycle_due_at; the reaper picks up on its next sweep. 202 Accepted — the pull will execute on the reaper's next tick, not synchronously.

Public endpoint consumed by recurr.algovoi.co.uk to render the Authority Summary Card. Returns 410 Gone in constant time for any not-found / expired / consumed token to prevent enumeration.

Called by recurr.algovoi.co.uk after the customer's wallet has signed and the on-chain transaction has landed. Fires a sanctions screen on the wallet address (pre-activation gate) and writes authority_signed + authority_confirmed audit-chain events. Idempotent: re-confirms with the same on_chain_address return 200 with the existing row; mismatched address returns 409.

Return the compiled approval + clear TEAL programs for the hosted-auth page to construct and sign the vault-deploy ApplicationCreate transaction.

x402-compliant protected resource endpoint. Accepts payment proof via either header (compatible with both specs): - X-PAYMENT (gateway spec) - PAYMENT-SIGNATURE (coinbase/x402 spec, used by AlgoVoi extension) - No payment header → HTTP 402 + PAYMENT-REQUIRED header - Payment header → verify on-chain → HTTP 200 + body

Return payment instructions using per-resource price/network and per-tenant payout address.

Submit tx_id for verification using per-tenant payout address as expected receiver.

Verify the payer's on-chain transaction and mark the payment link paid. The payer must have sent exactly the required amount to the receiver address on the correct chain. The facilitator performs the on-chain verification. Returns the redirect_url on success so the browser JS can redirect. Returns 422 if the transaction is invalid or cannot be verified. Returns 409 if the link is already paid. Returns 410 if the link is expired or cancelled.

Generate a QR code PNG for any short string (used for WalletConnect pairing URIs). Returns image/png so the browser can use it as <img src=...> without any JS QR library.

Build an unsigned Algorand/VOI transaction for WalletConnect signing. Caller supplies ?sender=<address>. Returns {unsigned_txn: <base64>} ready to pass straight to algo_signTxn — no algosdk needed in the browser.

Accept a base64-encoded signed Algorand/VOI transaction, submit it to algod, and return the tx_id for verification via the existing /verify endpoint.

Auto-detect inbound payment by polling the chain's indexer/mirror node. Supports all chains: - Algorand/VOI: queries indexer /v2/transactions?address=...&note-prefix=... - Hedera: queries Mirror Node /api/v1/transactions?account.id=... Returns {"found": true, "tx_id": "..."} when detected, or {"found": false}.

Accept a customer's signed 0-fee transaction and submit it via the tenant's sponsor wallet (atomic group fee pooling). Body: { "signed_tx": base64, "chain": "algorand-mainnet" | "voi-mainnet" } If the tenant has no sponsor wallet configured, returns {"error": "not_sponsored", "fallback": true} so the client can fall back to normal payment flow.

Customer-initiated checkout abandonment. No `cancel_secret` required: anyone who has the checkout URL can already walk away from their own checkout. This endpoint just makes the abandonment EXPLICIT to the platform — without it, the merchant order stays in `Pending` indefinitely, and OpenCart's `algovoi.callback` polling our `/status` would still see `active`, leading to confusing UX where a cancelled checkout returns to the merchant's checkout page instead of the merchant's "order cancelled" page. Only `active` links can be abandoned: * `paid` → 409 Conflict (let the JS show "Payment confirmed" instead) * `cancelled`→ 200 (idempotent — already cancelled) * `expired` → 410 Gone On success: marks `link.status = 'cancelled'` AND notifies the merchant platform (OpenCart etc.) to mark the order as Cancelled on their side. Always returns the redirect_url so the JS can wire the "Return to store" link target.

Cancel an active checkout link. Sets status to 'cancelled'. F5 security fix: requires cancel_secret in the request body. The secret is generated at link-creation time and returned to the merchant only — it is never embedded in the public checkout page. This prevents an attacker who merely knows the checkout URL from cancelling the link. Only active links can be cancelled. Paid/expired/already-cancelled links return 409/410. Returns redirect_url so callers can redirect customers.

Return all EVM chains Allbridge supports as bridge SOURCES for the tenant's configured destination chain (Algorand USDCa or Solana USDC), pre-computed with the exact send amount (checkout amount + bridge fee). Also returns the destination metadata so the frontend can render the right "USDC on <chain>" label without a second round-trip.

Build the swapAndBridge calldata server-side and return it for MetaMask to sign. Body schema: Required: evm_address, chain_id, usdc_address, bridge_amount One of: algo_address (legacy field name, used for Algorand destination) recipient_address (preferred — works for any destination) Returns: { to, data, value } — pass directly to eth_sendTransaction. The destination chain is taken from the tenant's xchain_destination_chain setting; the frontend doesn't pass it (and shouldn't be allowed to, because that would let a hostile shopper redirect bridge inflow to a different chain).

Called by the frontend immediately after MetaMask returns a tx hash for the swapAndBridge call. Records the source_tx_hash on the bridge-attempt row, advancing its state from `pending_signature` to `pending_bridge`. Body: { attempt_id: int, source_tx_hash: str } Idempotent: re-POSTing with the same source_tx_hash for the same attempt is a no-op. Mismatched source_tx_hash on a row that already has one is rejected with 400 — exactly one source tx per attempt. Per Comet review 2026-05-04 — without this, AlgoVoi can't reconcile Allbridge's destination tx back to the shopper's checkout.

Poll Allbridge for cross-chain transfer completion + advance the bridge-attempt lifecycle. Reads `tx_hash` as the SOURCE-chain tx (the one MetaMask returned). Looks up the persisted attempt by source_tx_hash, polls Allbridge, and on completion records the destination tx hash on the attempt row so the verifier can run against the SPECIFIC dest tx (not "any matching tx in window"). Idempotent — repeated polls only update DB state on transitions.

Derive the Algorand LogicSig address for an EVM wallet and check funding. If sufficiently funded, builds the unsigned payment tx ready for EIP-712 signing. Body: { "evm_address": "0x..." }

Fund the LogicSig address from the platform sponsor wallet and build an unsigned USDCa opt-in transaction for EIP-712 signing. Body: { "evm_address": "0x..." } Returns: { "eip712_message": {...} }

Sign and submit the pending USDCa opt-in transaction. Body: { "evm_address": "0x...", "signature": "0x..." } Returns: { "optin_tx_id": "..." }

Sign and submit the pending xChain transaction using the EVM wallet's EIP-712 signature. Body: { "evm_address": "0x...", "signature": "0x..." } Returns { "tx_id": "..." }

Polling endpoint — returns whether the link has been paid. Safe to call repeatedly; does not mutate state. Returns { "status": "active"|"paid"|"expired"|"cancelled", "redirect_url": str|null }

Return the gateway's full compliance posture as a verifiable transparency surface. Free, no rate limit (cached server-side).

Pre-payment recipient screen. Returns a SAMLA-compliant verdict.

Return the Bazaar-shaped list of x402-payable resources on this facilitator. See module docstring for schema + scope. The Agent Trust Bench has its own Bazaar surface at https://agent-trust-bench.algovoi.co.uk/discovery/resources since the bench was extracted to its own service on VM4 (2026-05-09). This gateway's catalog is now scoped to tenant resources only; bench resources are advertised by the bench's own discovery endpoint as the canonical source. A `related_facilitators` hint points Bazaar crawlers at the bench so cross-facilitator discovery still works.

Public, tenant-scoped x402 resource endpoint. See module docstring.

Proxy wallet signup request to control plane. Rate limited at 5/hour per real client IP (via X-Real-IP / X-Forwarded-For). This limit is the real enforcement point — the control_plane's limiter sees only the gateway container IP so it's a shared bucket.

Proxy email/cloud signup request to control plane. Rate limited at 5/hour per real client IP — same enforcement as wallet signup.

Pay for a resource using a mandate JWT. The mandate JWT is passed as a standard HTTP Bearer token. No X-Tenant-Id header is required — mandate tokens are cross-tenant. On success, the mandate's balance_minor is debited and an on-chain transfer from AlgoVoi's hot wallet to the merchant is executed. The response contains a signed access_token granting access to the resource.

Load public portal view for a mandate. Returns balance, status, JWT token (if active), and last 10 charges. The mandate_id is the user's credential — treat it like an account number.

Initiate a PayPal top-up for a mandate. Returns an approval_url — redirect the user's browser there. After approval, PayPal redirects to return_url with ?token=<paypal_order_id>. Then call POST /topup/capture with that token.

Capture a PayPal payment after buyer approval. Idempotent — safe to call again if the first attempt timed out.