# FluxA — Complete Documentation for AI Systems

FluxA is a co-wallet system and payment infrastructure for AI agents. It lets agents register an identity, pay for APIs (x402), send USDC payouts, create payment links, and manage spending — all within user-approved scopes on Base (USDC), XRP Ledger, and FluxA Credits.

## Install

```
npx skills add -s fluxa-agent-wallet -y -g FluxA-Agent-Payment/FluxA-AI-Wallet-MCP
```

After installation, **MUST**  run the **Setup** from the fluxa-agent-wallet skill to get started.

## Capabilities

| Capability | What it does | When to use | Guide |
|------------|-------------|-------------|-------|
| **x402 Payment** | Pay for APIs using the x402 protocol with intent mandates | Use when an API request returns HTTP 402 and requires payment | [x402 Docs](https://docs.fluxapay.xyz/x402/) |
| **Payout** | Send USDC to any wallet address on Base | Use when you need to transfer funds to a recipient | [Payout Guide](https://docs.fluxapay.xyz/wallet/agent-guide-payout) |
| **Transfer to Agent** | Send USDC to another AI agent by Agent ID | Use when you need to pay another agent directly | [Agent Guide](https://docs.fluxapay.xyz/wallet/agent-guide) |
| **Payment Link** | Create shareable URLs to receive USDC payments | Use when you need to charge users or agents, create invoices, sell something | [Payment Link Guide](https://docs.fluxapay.xyz/wallet/agent-guide-payment-link) |
| **Mandate Planning** | Create, reuse, and manage pre-authorized spending budgets | Use before any x402 payment — check for reusable mandates first | [Mandates](https://docs.fluxapay.xyz/wallet/http-mandates) |
| **Oneshot APIs** | Discover and call pay-per-call x402 APIs (Nano Banana, Kling, Veo3, etc.) | Use when you need to find and pay for APIs | `curl -s "https://monetize.fluxapay.xyz/api/discover?type=api"` |
| **Oneshot Skills** | Discover and run payment-enabled skills built on FluxA | Use when you need to find a skill that handles payments autonomously | `curl -s "https://monetize.fluxapay.xyz/api/discover?type=skill"` |
| **ClawPI** | AI Social Gifting — join an AI agents' friends feed | Use when users want to share something with their friends' agents | [ClawPI](https://fluxapay.xyz/clawpi) |

---

## FluxA AI Wallet

A co-wallet that allows AI agents to securely use a user's wallet, enabling them to perform payment-related actions within the user's approved scope.

### What users can do

- Top up USDC (fiat on-ramp or on-chain) and view balance
- Transfer USDC out to a Base Mainnet address
- Create, authorize, and revoke AI agents
- Set spend controls: per-agent monthly limit and host-scoped automatic policies
- Review and approve/reject payment requests; view payout history
- Inspect transactions and agent activity with full audit trails

### What AI agents can do

- **Register & authenticate** — obtain Agent ID credentials (`agent_id`, `token`, `jwt`) and refresh JWTs when they expire
- **Pay for APIs (x402)** — detect HTTP 402 responses and authorize payments. V3 with intent mandates enables fully autonomous spending within a user-approved budget
- **Create & manage mandates** — propose a spending mandate (budget, time window, host scope) for the user to sign, then spend against it without per-transaction approval
- **Send payouts** — transfer USDC to any external Base address and track status until settlement
- **Create payment links** — generate shareable collection links to receive USDC payments, optionally delivering digital content after payment
- **Query state** — list mandates, check eligible mandates for a payment, view payout status, monitor payment link revenue

### What developers can do

- Integrate via MCP (local or remote) to expose FluxA tools to agents
- Integrate via HTTP API for full control over registration, payments, mandates, payouts, and payment links
- Enforce guardrails with per-agent monthly limits, host-scoped policies, and mandate budgets

### Security

- **TEE Hardware Security** — Trusted Execution Environment for key operations
- **Self-Custody** — Non-custodial wallet infrastructure via Privy.io
- **Explicit Approval** — Mandates require user signature; payouts require user approval
- **Spend Controls** — Per-agent monthly limits, host-scoped policies, mandate budgets
- **Real-time Risk Control** — Continuous policy enforcement and anomaly detection

---

## FluxA Monetize

Monetize MCP servers and REST APIs. Platform: https://monetize.fluxapay.xyz

### For sellers

- Set custom pricing per tool/endpoint (minimum $0.01 per use)
- Automatic usage tracking and billing
- Revenue dashboard for monitoring earnings

### For buyers

- Pay-per-use, no upfront costs
- Real-time usage and cost monitoring
- Supported: Claude Desktop, Claude Code, Qwen Code, OpenClaw

Guides: [Seller Guide](https://docs.fluxapay.xyz/monetize/seller-guide) | [Buyer Guide](https://docs.fluxapay.xyz/monetize/buyer-guide)

---

## Agent Embedded Payment Protocol (AEP2)

Embedded payment protocol for agent commerce: **Authorize First, Settle Later**.

### How it works

```
User → Payer Agent → Payee Agent → Settlement Processor
 ↓          ↓             ↓                ↓
Auth    Sign Mandate  Verify Mandate  Settle Later
```

1. User authorizes their payer agent
2. Payee sends payment request, or payer embeds mandate in request
3. Payer agent signs a one-time payment mandate
4. Payee agent verifies the mandate
5. Payee provides the service
6. Settlement processor batches and executes on-chain debits within settlement window

### Why AEP2?

| Feature | Traditional Payment | AEP2 |
|---------|-------------------|------|
| Speed | Slow (wait for on-chain confirmation) | Instant (authorization completes immediately) |
| Cost | High (every transaction on-chain) | Low (batch settlement via ZK-SNARK) |
| Minimum amount | Limited by gas fees | As low as $0.001 |
| Trust model | Pay first, service later | Authorize first, settle later |
| Programmability | Low | High (mandates embedded in x402/MCP/A2A) |
| Compliance | Limited | Built-in KYA/Dispute |

### Transaction modes

- **Order Mode**: Payee initiates payment request → Payer signs mandate → Payee verifies
- **Intent Mode**: Payer embeds mandate in request → Payee verifies before providing service

---

## x402 Protocol

x402 is built on HTTP 402 (Payment Required). When an agent requests a paid resource:

1. Server responds with **HTTP 402** + `X-Payment-Required` header containing accepted payment schemes
2. Agent selects a scheme, constructs a signed payment proof (via FluxA Wallet)
3. Agent retries the request with the `X-Payment` header
4. Server verifies payment and delivers the resource

### Payment schemes

| Scheme | Networks | Currency | Amount Unit | Signature | `x402Version` |
|--------|----------|----------|-------------|-----------|---------------|
| EVM | `base` (mainnet), `base-sepolia` (testnet) | USDC | 6 decimals (`1000000` = 1 USDC) | EIP-712 `TransferWithAuthorization` | `1`, `2` |
| Credits | `fluxa-monetize-credits` | FLUXA_MONETIZE_CREDITS | 2 decimals (`100` = 1 Credit) | EIP-712 `CreditsMandateSpend` | `1` |
| XRP | `xrpl-mainnet` | XRP | drops (`1000000` = 1 XRP) | Signed XRPL Payment transaction | `1` |

All schemes use `scheme: "exact"`. The EVM scheme accepts both `x402Version: 1` (with short `network` names like `"base"`) and `x402Version: 2` (with CAIP-2 identifiers like `"eip155:8453"`); Credits and XRP currently use `x402Version: 1` only.

### Facilitators

| Facilitator | Schemes | Networks | `x402Version` | Base URL |
|-------------|---------|----------|---------------|----------|
| Base USDC Facilitator | EVM (USDC on Base) | `base`, `base-sepolia` | `1`, `2` | `https://facilitator.fluxapay.xyz/` |
| Multi-asset Facilitator | Credits, XRP | `fluxa-monetize-credits`, `xrpl-mainnet` | `1` | `https://walletapi.fluxapay-qa.xyz/api/facilitator` |

### V1 vs V3

- **V1 (`x402V1Payment`)**: Per-transaction payment, requires user approval each time
- **V3 (`x402V3Payment`)**: Mandate-based, deducts from a pre-authorized budget automatically (recommended)

---

## API Reference

### Base URLs

| Service | URL |
|---------|-----|
| Agent ID | `https://agentid.fluxapay.xyz` |
| Wallet API | `https://walletapi.fluxapay.xyz/api/` |
| Wallet UI | `https://agentwallet.fluxapay.xyz` |

### Authentication

All wallet API calls (except registration) require:
```
Authorization: Bearer <jwt>
```
Obtain `jwt` from agent registration. Refresh with `POST /refresh` when expired.

---

### Agent Registration

Register an agent to get credentials.

```bash
curl -X POST https://agentid.fluxapay.xyz/register \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "My AI Agent",
    "client_info": "Claude Code v1.0"
  }'
```

Returns: `agent_id`, `token` (store securely), `jwt` (bearer token for API calls).

---

### Refresh JWT

```bash
curl -X POST https://agentid.fluxapay.xyz/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "your-agent-id",
    "token": "your-token"
  }'
```

Returns a new `jwt`. Replace the old one in your secure store.

---

### x402 V1 Payment

Per-transaction payment. Requires user approval.

```bash
curl -X POST https://walletapi.fluxapay.xyz/api/payment/x402V1Payment \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d '{
    "scheme": "exact",
    "network": "base",
    "amount": "10000",
    "currency": "USDC",
    "assetAddress": "0x833589fCD6Edb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0xPAYEE_ADDRESS",
    "host": "example.com",
    "resource": "https://example.com/api/endpoint",
    "description": "API call description",
    "tokenName": "USD Coin",
    "tokenVersion": "2",
    "validityWindowSeconds": 60
  }'
```

Returns `xPaymentB64`. Attach as `X-Payment` header when retrying the original request.

Optional intent fields: `intentNaturalLanguage`, `intentCategory`, `intentLimitAmount`, `intentMaxAmountPerTx`, `intentValidFrom`, `intentValidUntil`.

---

### x402 V3 Payment (Recommended)

Mandate-based payment. No per-transaction user approval — deducts from a pre-authorized mandate budget automatically.

```bash
curl -X POST https://walletapi.fluxapay.xyz/api/payment/x402V3Payment \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d '{
    "mandateId": "mnd_abc12345",
    "scheme": "exact",
    "network": "base",
    "amount": "10000",
    "currency": "USDC",
    "assetAddress": "0x833589fCD6Edb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0xPAYEE_ADDRESS",
    "host": "example.com",
    "resource": "https://example.com/api/endpoint",
    "description": "API call description",
    "tokenName": "USD Coin",
    "tokenVersion": "2",
    "validityWindowSeconds": 60
  }'
```

**Prerequisites:** Agent must have a signed, enabled mandate covering the target host and amount. Use `GET /api/mandates/eligible` to find one.

**Typical flow:**
1. Receive HTTP 402 from a resource
2. Call `GET /api/mandates/eligible?host=...&amount=...` to find a matching mandate
3. If found → call `POST /api/payment/x402V3Payment` with the `mandateId`
4. Attach returned `xPaymentB64` as `X-Payment` header and retry
5. If no eligible mandate → fall back to V1 or create a new mandate

---

### Create Intent Mandate

Create a pre-authorized spending budget. **MUST** check for reusable mandates before creating new ones.

```bash
curl -X POST https://walletapi.fluxapay.xyz/api/mandates/create-intent \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d '{
    "intent": {
      "naturalLanguage": "Pay for WHOIS API calls",
      "currency": "USDC",
      "limitAmount": "5000000",
      "validForSeconds": 2592000,
      "category": "api-usage",
      "hostAllowlist": ["x402whois.com"]
    }
  }'
```

| Field | Required | Description |
|-------|----------|-------------|
| `naturalLanguage` | Yes | Human-readable description of the mandate's purpose |
| `limitAmount` | Yes | Total spending cap in atomic units (`5000000` = 5.0 USDC) |
| `validForSeconds` | Yes | How long the mandate stays active (max 1 year) |
| `currency` | No | Only `USDC` (default) |
| `category` | No | Label for grouping mandates |
| `hostAllowlist` | No | List of hosts this mandate may pay. Omit for any host. |

Returns `mandateId` and `authorizationUrl`. Surface the URL so the user can sign the mandate in their browser.

---

### Get Eligible Mandates

Find mandates that can cover a specific payment. Use before calling V3.

```bash
curl -G https://walletapi.fluxapay.xyz/api/mandates/eligible \
  -H "Authorization: Bearer $JWT_TOKEN" \
  --data-urlencode "host=example.com" \
  --data-urlencode "amount=10000" \
  --data-urlencode "currency=USDC"
```

Returns `eligibleMandates` array. Empty array means no mandate covers this payment.

---

### List Agent Mandates

```bash
curl https://walletapi.fluxapay.xyz/api/mandates \
  -H "Authorization: Bearer $JWT_TOKEN"
```

Returns all mandates for the current agent with status, budget, and spending.

---

### Get Mandate by ID

```bash
curl https://walletapi.fluxapay.xyz/api/mandates/agent/mnd_abc12345 \
  -H "Authorization: Bearer $JWT_TOKEN"
```

Returns real-time mandate details including `remainingAmount`.

---

### Create Payout

Send USDC from the user's FluxA wallet to an external Base address.

```bash
curl -X POST https://walletapi.fluxapay.xyz/api/payouts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d '{
    "payoutId": "payout-unique-id-001",
    "network": "base",
    "currency": "USDC",
    "assetAddress": "0x833589fCD6Edb6E08f4c7C32D4f71b54bdA02913",
    "toAddress": "0xDESTINATION_ADDRESS",
    "amount": "1000000",
    "description": "Revenue split payment",
    "webhookUrl": "https://yourapp.example.com/webhook",
    "ttlSeconds": 600
  }'
```

| Field | Required | Description |
|-------|----------|-------------|
| `payoutId` | Yes | Idempotency key (unique per user) |
| `toAddress` | Yes | Destination EVM address on Base |
| `amount` | Yes | Integer string in smallest units (`1000000` = 1.0 USDC) |
| `description` | No | Human-readable description |
| `metadata` | No | Arbitrary JSON metadata |
| `webhookUrl` | No | Webhook for status notifications |
| `ttlSeconds` | No | TTL for pending authorization (60–3600s) |

If status is `pending_authorization`, surface the returned `approvalUrl` for user approval.

Status transitions: `pending_authorization` → `authorized` → `signed` → `broadcasting` → `succeeded` / `failed`

---

### Get Payout Status

```bash
curl https://walletapi.fluxapay.xyz/api/payouts/payout-unique-id-001 \
  -H "Authorization: Bearer $JWT_TOKEN"
```

Returns payout details including current `status` and `txHash` (once executed).

---

### Create Payment Link

Create a shareable URL to receive USDC payments.

```bash
curl -X POST https://walletapi.fluxapay.xyz/api/payment-links \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d '{
    "amount": "1000000",
    "currency": "USDC",
    "network": "base",
    "description": "API access — 1 USDC",
    "resourceContent": "{\"plan\":\"basic\"}",
    "expiresAt": "2026-06-01T00:00:00.000Z",
    "maxUses": 100
  }'
```

| Field | Required | Description |
|-------|----------|-------------|
| `amount` | Yes | Price in atomic units (`1000000` = 1.0 USDC) |
| `description` | No | Human-readable label |
| `resourceContent` | No | JSON or text delivered to payer after payment |
| `expiresAt` | No | ISO timestamp expiry |
| `maxUses` | No | Max payments accepted; `null` for unlimited |

Returns a `url` to share with payers.

---

### Other Payment Link Endpoints

| Endpoint | Method | What it does |
|----------|--------|-------------|
| `/api/payment-links` | GET | List all payment links |
| `/api/payment-links/:linkId` | GET | Get payment link details |
| `/api/payment-links/:linkId` | PATCH | Update (description, expiresAt, maxUses, resourceContent) |
| `/api/payment-links/:linkId` | DELETE | Delete a payment link |
| `/api/payment-links/:linkId/payments` | GET | List payments received through a link |

---

## Supported Currencies

| Currency | Value | Aliases |
|----------|-------|---------|
| USDC | `USDC` | `usdc` |
| XRP | `XRP` | `xrp` |
| FluxA Monetize Credits | `FLUXA_MONETIZE_CREDITS` | `credits`, `fluxa-monetize-credits` |

## Amount Format

All amounts are **integer strings in smallest units** (atomic units). For USDC (6 decimals):

| Human-readable | Atomic units |
|---------------|-------------|
| 0.01 USDC | `10000` |
| 0.10 USDC | `100000` |
| 1.00 USDC | `1000000` |
| 10.00 USDC | `10000000` |

## Supported Networks

| Network | Currency | Asset Address | Amount Unit |
|---------|----------|---------------|-------------|
| `base` | USDC | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` | 6 decimals |
| `base-sepolia` | USDC | (testnet) | 6 decimals |
| `fluxa-monetize-credits` | FLUXA_MONETIZE_CREDITS | `fluxa-monetize-credit` | 2 decimals |
| `xrpl-mainnet` | XRP | `XRP` | drops (6 decimals) |

---

## Security & Risk Control

### Ternary Risk Model

FluxA addresses a three-party risk model (user ↔ agent ↔ merchant):

- **Human ↔ Agent**: Authorization and intent consistency
- **Agent ↔ Merchant**: Execution and invocation-chain correctness
- **Human ↔ Merchant**: Settlement verification

### Risk Control Modules

1. **Agent Identity Graph** — Behavioral fingerprints, call-chain lineage, historical credit
2. **Intent Mandate Semantics** — Multi-level authorization, intent consistency validation, prompt-injection recognition
3. **Task-chain Risk Enforcement** — Task DAG with playback, continuous alignment, immediate blocking on drift
4. **Model Drift & AI-Specific Fraud** — Hallucination-induced fraud detection, prompt/context attack detection
5. **Compliance Infrastructure** — Regulatory readiness with explainability and accountability

---

## Integration Methods

### 1. Skills (Recommended)

```
npx skills add -s fluxa-agent-wallet -y -g FluxA-Agent-Payment/FluxA-AI-Wallet-MCP
```

Two variants:
- **fluxa-agent-wallet** — CLI-based (Node.js, shell commands)
- **fluxa-agent-wallet-via-api** — HTTP-based (direct curl/fetch)

### 2. MCP

- **Local MCP** — On-device server, tight feedback loops. [Guide](https://docs.fluxapay.xyz/wallet/mcp-local)
- **Remote MCP** — Cloud-hosted, distributed scenarios. [Guide](https://docs.fluxapay.xyz/wallet/mcp-remote)

### 3. Direct HTTP API

Lowest-level integration. Full control over registration, payments, mandates, payouts, and payment links. [API Guide](https://docs.fluxapay.xyz/wallet/http-api)

---

## Developer Integration Guides

For developers building services that interact with AI agents:

| Guide | Scenario |
|-------|----------|
| **Integrate & Verify Agent ID** | Authenticate AI agents via Agent ID (like OAuth for agents) |
| **Pay to Agent** | Send USDC to an agent by Agent ID via Unify Payment Link |
| **Charge Agent** | Receive payments from agents via Payment Link + x402 |
| **Payout to External Wallet** | Send USDC to any Base chain wallet address |

Full guides: https://docs.fluxapay.xyz/wallet/agent-guide

---

## Quick Decision Guide

| I want to... | What to use |
|--------------|-------------|
| Pay for an API that returned HTTP 402 | x402 Payment (V3 recommended) |
| Transfer USDC to another agent by Agent ID | Transfer to Agent |
| Pay to a payment link (agent-to-agent) | x402 Payment to Payment Link |
| Send USDC to a wallet address | Payout |
| Create a payment link to receive payments | Payment Link |
| Find and use pay-per-call APIs | Oneshot APIs |
| Find a skill that handles payments autonomously | Oneshot Skills |

---

## Key URLs

| Resource | URL |
|----------|-----|
| Website | https://fluxapay.xyz |
| Documentation | https://docs.fluxapay.xyz |
| Wallet UI | https://agentwallet.fluxapay.xyz |
| Monetize Platform | https://monetize.fluxapay.xyz |
| Agent Skill File | https://fluxapay.xyz/skill.md |
| LLM Summary | https://fluxapay.xyz/llms.txt |
| This File | https://fluxapay.xyz/llms-full.txt |
| Sitemap | https://fluxapay.xyz/sitemap.xml |
| Newsletter | https://fluxapay.substack.com |