Skip to content

Feature Specification: Machine Payments Protocol (MPP) Implementation

1. Overview

The goal of this feature is to integrate the Machine Payments Protocol (MPP) (mpp.dev) into HeadlessDomains. This will allow AI agents to pay for domain registrations and renewals using stablecoins/fiat natively, securely, and without sharing private keys, serving as a secondary payment option alongside the default GFAVIP Gems.

2. Rationale

  • MPP is purpose-built for AI agent commerce.
  • It provides a native way for agents to use Tempo passkeys, Ironclaw (NEAR), Lightning, or Stripe.
  • It removes the friction of x402 and the need for external facilitators.
  • Integrating this makes HeadlessDomains significantly more appealing and accessible to the broader AI agent ecosystem.

3. Database Changes (models.py)

Add a new column to track the payment method used for domain registrations.

Table: domains - Add column: payment_method = db.Column(db.String(20), default='gems') # Can be 'gems' or 'mpp' - (Optional) Add column: payment_receipt = db.Column(db.String(255), nullable=True) # To store the MPP transaction/receipt ID for audit purposes.

4. Payment Flow & Route Changes

4.1. Domain Registration Endpoint (/register or /api/domains/register)

Modify the existing registration logic to support a two-step MPP flow when requested by the agent.

Logic Update: 1. Perform existing checks (TLD availability, user authentication, agent squad/coupon discounts). 2. Calculate the cost. If the cost is 0 (coupon applied), proceed with free registration immediately. 3. If cost > 0, check the client's preference. - Check Header: if request.headers.get('X-Payment-Method') == 'mpp': - Action (MPP Flow): Instead of deducting Gems, generate an MPP session and return an HTTP 402 Payment Required response.

Expected 402 Response Payload: 

{
  "status": "payment_required",
  "protocol": "mpp",
  "amount": 9.99, // Converted from Gems to USD/USDC if necessary
  "currency": "USDC", // or "pathUSD" depending on Tempo config
  "session_id": "mpp_session_xyz123", // Generated session UUID
  "pay_url": "https://pay.tempo.xyz/..." // Link for the agent to execute payment
}

4.2. Verification Endpoint (New: /api/payments/verify-mpp)

Create a new endpoint that the agent calls after successfully paying the pay_url.

Request: POST /api/payments/verify-mpp Payload: 

{
  "session_id": "mpp_session_xyz123",
  "receipt": "tempo_receipt_abc987",
  "domain": "my.chatbot",
  "tld": "chatbot",
  "years": 1
}

Logic: 1. Verify the receipt against the MPP/Tempo API to ensure payment was actually received for the correct amount. 2. If valid: - Call SkyInclude API to register/create the zone. - Save the domain to the database with payment_method='mpp' and payment_receipt=receipt. - Return HTTP 200 OK with success message. 3. If invalid: Return 400 Bad Request or 402 Payment Required.

4.3. Domain Renewal Endpoint (/renew)

Apply the exact same logic structure to the renewal endpoint: 1. Check for X-Payment-Method: mpp. 2. Return 402 with pay_url. 3. Allow verification via /api/payments/verify-mpp (or a specific renewal verification endpoint) which then updates the expiry_date.

5. Pricing Conversion (Gems to USD)

Since MPP operates in fiat/stablecoins (USD/USDC) and HeadlessDomains currently prices TLDs in "Gems", a conversion rate must be established. - Requirement: Define a fixed exchange rate (e.g., 1 Gem = $1.00 USD) or fetch dynamic pricing if required. - The 402 response must calculate cost_usd = tld.price * GEM_TO_USD_RATE.

6. Implementation Steps

  1. Branch Creation: Create a new git branch feature/mpp-payments.
  2. Models: Update models.py and create a migration script for payment_method.
  3. Helper File: Create utils/mpp.py to handle session generation and Tempo receipt verification logic.
  4. Routes:
  5. Update routes/domains.py (register and renew functions) to handle the 402 flow.
  6. Create the new /api/payments/verify-mpp route.
  7. Testing: Write unit tests simulating the 402 response and successful verification.
  8. Documentation: Update skill.md to instruct AI agents on how to use the X-Payment-Method: mpp header and handle the 402 response.

7. Open Questions / Dependencies

  • Need exact API keys/secrets for Tempo/MPP integration to verify receipts.
  • Need to finalize the Gem-to-USD conversion rate for the MPP payload.