---
name: inventingenius-x402-xrpl
description: Handles x402 Payment Required responses from api.inventingenius.com. Detects 402 challenges, guides XRPL wallet setup (testnet first), registers the agent, checks balance, prepares/presigns payments via t54.ai XRPL facilitator (XRP/RLUSD), and retries requests. Minimizes human friction with clear top-up prompts and safety rules.
license: MIT
metadata:
  author: InventingGenius (api.inventingenius.com)
  version: "1.0.0"
  category: payments
  tags: [x402, xrpl, xrp, rlusd, micropayments, agent-payments]
compatibility: Works with Hermes, Claude Code/Desktop, Cursor, and other SKILL.md-compatible agents. Requires xrpl.js or xrpl-py access (or terminal/tool calling for scripts). Internet access for RPC/facilitator.
---

# InventingGenius x402 + XRPL Bootstrap Skill

**Purpose**: Make agents pay seamlessly for APIs on https://api.inventingenius.com using XRP or RLUSD via the x402 standard and t54.ai XRPL facilitator. This skill bootstraps wallet setup, registration, payment handling, and retries with minimal human intervention.

## Activation Triggers
- Receive HTTP 402 Payment Required from `api.inventingenius.com` (or any inventingenius domain).
- User/agent mentions "pay for InventingGenius", "x402", "top up wallet", or "XRP payment".
- Balance check or payment preparation requested for this service.

## Core Principles (Non-Negotiable)
1. **Safety First**: Never expose seeds/private keys in chat. Write to `.env` immediately. Always preview payments before signing.
2. **Testnet First**: Default to testnet for all new setups. Only switch to mainnet after explicit confirmation and successful test payments.
3. **Human-in-the-Loop for Funding**: Agents cannot autonomously onramp fiat/crypto on mainnet. Output clear, copy-paste instructions + QR (if possible) for humans.
4. **Idempotency & Retry**: Always retry the original request after successful payment.
5. **No Custody**: Use presigned transactions via t54.ai facilitator.

## Step-by-Step Procedures

### 1. Wallet Setup (if none exists)
- Check for existing `XRPL_SEED` or configured wallet.
- If missing: Generate a new wallet using `xrpl.js` / `xrpl-py`.
  - Immediately write seed to `.env` (never echo in output).
  - Display **only** the classic address.
- Recommend funding via Testnet faucet first: https://xrpl.org/resources/dev-tools/xrp-faucets
- Register the agent at your endpoint: `POST /api/v1/agent/register/` with the wallet address.

### 2. Handle 402 Response
When you receive a 402 from api.inventingenius.com:
- Parse the response for required amount, asset (XRP/RLUSD), pay-to address, invoice ID, etc.
- Check current balance via XRPL RPC.
- If sufficient:
  - Prepare Payment transaction.
  - Preview to human (or auto-sign if override active).
  - Sign locally.
  - Submit presigned blob to t54.ai facilitator (`https://xrpl-facilitator-mainnet.t54.ai` or testnet equivalent).
  - On success: Retry original request with payment proof.
- If insufficient: Output exact top-up request.

### 3. Payment Preparation & Facilitator Flow
- Use t54.ai XRPL facilitator for verification/settlement (no custody).
- Bind payment to invoice ID from 402 response.
- Preferred assets: XRP (fast/cheap) or RLUSD.
- After settlement confirmation, include proof in retry headers.

### 4. Registration & Balance Management
- Always register new wallets via your `/api/v1/agent/register/` for balance tracking and proxy features.
- Periodically check and report remaining balance (use headers like `X-Balance-Remaining` if available).

## Examples

**Example 402 Handling**:
1. Detect 402 -> "Payment Required: 0.5 XRP"
2. Check balance -> Insufficient -> Output top-up message.
3. After funding -> Prepare, sign, submit via facilitator -> Retry API call.

**Test Flow**:
- Create test wallet -> Fund via faucet -> Register -> Make first call to a free/test endpoint.

## Common Edge Cases & Troubleshooting
- Low XRP reserve: Remind user XRPL accounts need ~1-2 XRP base reserve.
- Transaction failed: Check `tec*` / `tesSUCCESS` codes and retry with higher fee if needed.
- Mainnet switch: Require explicit human confirmation + small test payment first.
- Rate limits / ASTEROID (free) tier: Respect your ASTEROID tier quota before prompting payment.

## Integration Tips
- Combine with Ripple XRPL Agent Wallet Skill and XRPL Payment Skill for best results.
- For Hermes: Place this skill in your skills directory and reload.
- For Claude/Cursor: Install via skills system.
- Monitor transactions on https://xrpscan.com or testnet explorer.

**Support**: Visit https://api.inventingenius.com for docs, guides, and live demos. This skill is designed to get you from 402 -> paying customer in minutes.

---
*Maintained for seamless agent payments on InventingGenius APIs. Update version as facilitator APIs evolve.*