> ## Documentation Index
> Fetch the complete documentation index at: https://docs.0xmeta.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# FAQ

> Frequently asked questions about 0xmeta facilitator with pre-settlement fee collection

## General Questions

<AccordionGroup>
  <Accordion title="Do I need an account to use 0xmeta.ai?">
    **No!** The facilitator is permissionless. No signup, no API keys, no registration.

    Just:

    1. Approve facilitator for USDC spending (one-time)
    2. Integrate x402 middleware
    3. Start accepting payments
  </Accordion>

  <Accordion title="What is x402?">
    x402 is a protocol for HTTP-based payments. It's like a "402 Payment Required" status code, but with built-in payment authorization using blockchain signatures.

    **Key principle:** Customers pay merchants directly (no intermediaries).
  </Accordion>

  <Accordion title="What networks are supported?">
    Currently:

    * **Base Mainnet** (Chain ID: 8453)
    * **Base Sepolia** (Chain ID: 84532, testnet)

    More networks coming soon.
  </Accordion>
</AccordionGroup>

***

## Merchant Setup

<AccordionGroup>
  <Accordion title="Why do I need to approve the facilitator?">
    **Technical reason:** The facilitator collects a \$0.01 fee per settlement from your USDC balance using the standard ERC-20 `transferFrom` pattern **before** executing the settlement.

    **How it works:**

    ```solidity theme={null}
    // You approve facilitator (one-time)
    USDC.approve(treasury, 100 * 10^6); // 100 USDC

    // Before each settlement, facilitator collects fee FIRST
    USDC.transferFrom(merchant, treasury, 0.01 * 10^6); // $0.01

    // Then executes customer → merchant payment
    ```

    **Why this pattern:**

    * x402 requires customers pay merchants directly (trust-minimization)
    * Facilitator can't split customer payments
    * Pre-settlement fee collection prevents free service exploitation
    * Solution: Merchant pays fee separately via approval, BEFORE settlement
  </Accordion>

  <Accordion title="How do I approve the facilitator?">
    Use our provided script:

    ```bash theme={null}
    # Configure
    export EVM_PRIVATE_KEY=0x...
    export NETWORK=mainnet  # or sepolia

    # Run approval
    node approve-facilitator.mjs
    ```

    This approves the facilitator treasury to spend USDC on your behalf.

    See [x402 Integration Guide](/x402-integration#merchant-approval-setup) for details.
  </Accordion>

  <Accordion title="How much should I approve?">
    **Recommended:** 100-1000 USDC

    **Calculation:** `Approval = Settlements × $0.01`

    Examples:

    * 100 USDC = 10,000 settlements
    * 500 USDC = 50,000 settlements
    * 1000 USDC = 100,000 settlements

    **Avoid:** Infinite approval (max uint256) for security reasons.
  </Accordion>

  <Accordion title="Can I revoke approval?">
    **Yes!** At any time:

    ```bash theme={null}
    # Set approval to 0
    APPROVAL_AMOUNT=0 node approve-facilitator.mjs
    ```

    **Effect:** All future settlements will fail at the pre-settlement fee collection step with `insufficient_allowance` error. Customers won't be charged.

    To resume: Re-run approval with desired amount.
  </Accordion>

  <Accordion title="How do I check my remaining allowance?">
    Use our monitoring script:

    ```bash theme={null}
    node check-allowance.mjs

    # Output:
    # 📍 Base Mainnet
    #    USDC Balance: 500.00 USDC
    #    Fee Allowance: 95.50 USDC
    #    Settlements: 9,550
    #    ✅ Good
    ```

    Set up automated monitoring via cron or alerts.
  </Accordion>
</AccordionGroup>

***

## Trust & Security

<AccordionGroup>
  <Accordion title="How do I know the facilitator won't steal customer funds?">
    **It's cryptographically impossible.**

    **Why:**

    1. Customers authorize payments directly to **your address** (not facilitator)
    2. EIP-3009 signatures are cryptographically bound to recipient
    3. Facilitator has zero access to customer authorizations
    4. Facilitator cannot redirect customer funds

    **Technical details:**

    ```javascript theme={null}
    // Customer signs authorization
    const authorization = {
      from: customerAddress,
      to: YOUR_MERCHANT_ADDRESS,  // ← Cryptographically bound
      value: "20000",
      signature: "0x..."
    };

    // Facilitator can only execute this EXACT transfer
    // Cannot change recipient or amount
    ```

    This is the core principle of x402: **trust-minimization**.
  </Accordion>

  <Accordion title="Can the facilitator drain my USDC balance?">
    **No.** Only the approved amount is accessible.

    **Example:**

    * You approve: 100 USDC
    * Maximum risk: 100 USDC
    * Your remaining USDC: Safe

    **Pre-settlement protection:** Fee collected BEFORE settlement. If you have insufficient balance, settlement is blocked and customer isn't charged.

    **Best practice:** Approve reasonable amounts (100-1000 USDC), not infinite.

    **Monitoring:** Use `check-allowance.mjs` to track remaining approval.
  </Accordion>

  <Accordion title="What if the facilitator is hacked?">
    **Worst case:** Attacker drains your approved amount only.

    **Protection:**

    1. **Limit approval:** Don't approve more than you're willing to risk
    2. **Monitor regularly:** Check allowance frequently
    3. **Revoke if suspicious:** Set approval to 0 immediately

    **Your customer funds:** Always safe (facilitator has no access).

    **Pre-settlement benefit:** Attacker can only collect fees for settlement attempts, not steal customer funds.
  </Accordion>

  <Accordion title="Is this more secure than traditional payment processors?">
    **Yes, in several ways:**

    **Traditional:**

    * ❌ Custody of customer funds
    * ❌ Can freeze/hold payments
    * ❌ Opaque settlement process

    **0xmeta (x402 with pre-settlement):**

    * ✅ No custody (direct to merchant)
    * ✅ Cannot freeze payments
    * ✅ On-chain auditable
    * ✅ Cryptographic guarantees
    * ✅ Fee collected before settlement (no free service)

    **Trade-off:** Requires blockchain familiarity and USDC approval.
  </Accordion>
</AccordionGroup>

***

## Fees & Pricing

<AccordionGroup>
  <Accordion title="How are fees collected?">
    **Pre-settlement via transferFrom:**

    **Flow:**

    1. Customer authorizes \$0.02 to your address
    2. **Facilitator collects \$0.01 fee from your approved USDC balance FIRST**
    3. **Then** facilitator executes customer → merchant payment (\$0.02)
    4. You receive 100% of customer payment (\$0.02)

    **Technical:**

    ```solidity theme={null}
    // Step 1: Collect fee from merchant FIRST (pre-settlement)
    transferFrom(merchant, treasury, 10000); // $0.01

    // Step 2: Execute customer → merchant (AFTER fee)
    transferWithAuthorization(customer, merchant, 20000); // $0.02
    ```

    **Key:** No fee collection = no settlement. This prevents free service.
  </Accordion>

  <Accordion title="Why does the merchant pay the fee, not the customer?">
    **Technical constraint:** x402 requires customer payments go directly to merchants (trust-minimization). EIP-3009 signatures are cryptographically bound to exact recipient and amount. Cannot split customer payment.

    **Solution:** Merchant pays facilitator fee separately via standard ERC-20 approval, collected **before** settlement execution.

    **Merchant pricing:** Add fee to your prices:

    * Your price: \$0.01
    * Facilitator fee: \$0.01
    * Customer pays: \$0.02

    **Economic protection:** Pre-settlement collection ensures merchant pays for service.
  </Accordion>

  <Accordion title="What if settlement fails after fee collection?">
    **You paid \$0.01 for the settlement attempt.**

    **Why this is fair:**

    * Facilitator verified customer authorization
    * Facilitator attempted settlement execution
    * Resources were consumed (RPC calls, API calls, gas estimation)
    * Service was rendered

    **Why pre-settlement:** Without collecting fee first, merchants could intentionally cause settlement failures to get free verification service. Pre-settlement prevents this exploitation.

    **Mitigation:** Test thoroughly on Base Sepolia testnet before production. Monitor settlement success rates.
  </Accordion>

  <Accordion title="Are there any hidden fees?">
    **No.**

    **What you pay:**

    * \$0.01 USDC per settlement (collected pre-settlement)

    **What you DON'T pay:**

    * ❌ Monthly fees
    * ❌ Setup fees
    * ❌ Gas fees (facilitator pays)
    * ❌ Withdrawal fees
    * ❌ Percentage fees
    * ❌ Minimum volume requirements

    **Transparency:** Every fee collection is an on-chain transaction you can verify.
  </Accordion>
</AccordionGroup>

***

## Technical Questions

<AccordionGroup>
  <Accordion title="What happens if I revoke approval mid-settlement?">
    **Settlement fails at pre-settlement fee collection step.**

    **Flow:**

    1. Customer submits payment authorization
    2. Facilitator attempts fee collection (pre-settlement)
    3. Fee collection fails (approval revoked)
    4. Settlement BLOCKED
    5. Customer NOT charged

    **Error response:**

    ```json theme={null}
    {
      "error": {
        "code": "insufficient_allowance",
        "message": "Merchant must approve facilitator",
        "details": {
          "note": "Settlement blocked - customer not charged"
        }
      }
    }
    ```

    **Customer protection:** Pre-settlement means if fee collection fails, settlement never executes.
  </Accordion>

  <Accordion title="Can I use a different token besides USDC?">
    **Not yet.** Currently only USDC is supported.

    **Roadmap:** Multi-token support planned (USDT, DAI, etc.)

    **Why USDC first:** Most stable, widely adopted, best EIP-3009 support.
  </Accordion>

  <Accordion title="How do I test on testnet?">
    **Use Base Sepolia:**

    ```bash theme={null}
    # 1. Get testnet USDC (Circle faucet)
    # 2. Approve facilitator on testnet
    NETWORK=sepolia node approve-facilitator.mjs

    # 3. Configure server for testnet
    # network: "eip155:84532" (v2) or "base-sepolia" (v1)

    # 4. Test payments
    ```

    **Testnet addresses:**

    * USDC: `0x036CbD53842c5426634e7929541eC2318f3dCF7e`
    * Treasury: `0x5D791e3554D0e83f171126905Bda1640Bf6f9A8B`

    **Recommendation:** Thoroughly test pre-settlement fee collection on Sepolia before mainnet.
  </Accordion>

  <Accordion title="What's the difference between x402 v1 and v2?">
    **Network format:**

    * **v1:** `"base-sepolia"` (string)
    * **v2:** `"eip155:84532"` (CAIP-2 format)

    **Both supported!** Use v2 for new integrations.

    **Pre-settlement works the same in both versions.**

    **Migration:** See [x402 Integration Guide](/x402-integration#migration-v1-v2)
  </Accordion>

  <Accordion title="How long do settlements take?">
    **Typical timing:**

    * Verification: \< 2 seconds
    * **Pre-settlement fee collection: 5-10 seconds** (on-chain tx)
    * Settlement execution: 30-60 seconds (via 1Shot)

    **Total:** 35-70 seconds average

    **Key:** Fee collection happens FIRST, then settlement. If fee collection fails, settlement never starts.

    **Factors:**

    * Network congestion
    * RPC provider latency
    * 1Shot API processing time
  </Accordion>

  <Accordion title="Can I see all transactions on-chain?">
    **Yes!** All transactions are public.

    **Pre-settlement fee collection:**

    ```
    https://basescan.org/tx/{fee_tx_hash}
    ```

    **Settlement (after fee):**

    ```
    https://basescan.org/tx/{settlement_tx_hash}
    ```

    **Merchant address activity:**

    ```
    https://basescan.org/address/{your_merchant_address}
    ```

    **Verification:** You can verify fee was collected BEFORE settlement execution by comparing timestamps.
  </Accordion>

  <Accordion title="Why pre-settlement instead of post-settlement?">
    **Economic security and sustainability:**

    **Pre-settlement (current):**

    * ✅ Fee collected FIRST
    * ✅ If fee fails → settlement blocked → customer safe
    * ✅ No free service exploitation
    * ✅ Sustainable business model

    **Post-settlement (rejected):**

    * ❌ Settlement executes first
    * ❌ Fee collection could fail → free service
    * ❌ Merchants could exploit for free verification
    * ❌ Unsustainable

    **Trade-off:** Merchant pays \$0.01 even if settlement fails after fee. This is fair payment for the attempt.
  </Accordion>
</AccordionGroup>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Error: insufficient_allowance">
    **Cause:** You haven't approved facilitator, or approval is depleted.

    **Solution:**

    ```bash theme={null}
    # Check current allowance
    node check-allowance.mjs

    # If low/zero, approve more
    node approve-facilitator.mjs
    ```

    **Pre-settlement:** This error occurs at fee collection step, BEFORE settlement. Customer is not charged.
  </Accordion>

  <Accordion title="Error: fee_collection_failed">
    **Cause:** Your USDC balance is insufficient for the \$0.01 fee.

    **Solution:** Add USDC to your merchant address.

    **Check balance:**

    ```bash theme={null}
    node check-allowance.mjs
    # Shows: USDC Balance: 0.00 USDC ← Problem
    ```

    **Critical:** This is a pre-settlement error. Settlement never executed, customer not charged.
  </Accordion>

  <Accordion title="Settlement taking too long">
    **Normal:** 35-70 seconds

    **If longer:**

    1. Check if pre-settlement fee collection succeeded
    2. Check Base network status
    3. Verify 1Shot API status
    4. Check settlement status via API

    **Polling:**

    ```javascript theme={null}
    const status = await checkSettlement(settlement_id);
    // status: "pending" | "settled" | "failed"
    ```

    **Note:** Fee is collected in first 5-10 seconds. Remaining time is settlement execution.
  </Accordion>

  <Accordion title="How do I get support?">
    **Options:**

    1. **Documentation:** [https://docs.0xmeta.ai](https://docs.0xmeta.ai)
    2. **GitHub Issues:** [https://github.com/0xmetaHQ/x402-facilitator/issues](https://github.com/0xmetaHQ/x402-facilitator/issues)
    3. **Email:** [support@0xmeta.ai](mailto:support@0xmeta.ai)
    4. **Discord:** [https://discord.gg/0xmeta](https://discord.gg/0xmeta)

    **Include:**

    * Settlement ID or verification ID
    * Error message (if applicable)
    * Network (mainnet or sepolia)
    * Whether error occurred at fee collection or settlement
  </Accordion>
</AccordionGroup>

***

## Comparison to Alternatives

<AccordionGroup>
  <Accordion title="How is this different from other x402 facilitators?">
    **0xmeta:**

    * ✅ Paid service (\$0.01/settlement, pre-settlement)
    * ✅ Production-ready infrastructure
    * ✅ Guaranteed uptime (99.9% SLA)
    * ✅ Professional support
    * ✅ No free service exploitation (pre-settlement)

    **Free facilitators:**

    * ⚠️ May shut down anytime
    * ⚠️ No guarantees
    * ⚠️ Limited support
    * ⚠️ May use post-settlement (exploitable)

    **Trade-off:** Pay for reliability and economic sustainability vs. free but uncertain.
  </Accordion>

  <Accordion title="Why use a facilitator at all?">
    **Without facilitator:**

    * ❌ You verify signatures yourself
    * ❌ You execute settlements on-chain
    * ❌ You pay gas fees
    * ❌ You handle errors/retries
    * ❌ Complex infrastructure

    **With 0xmeta:**

    * ✅ Signature verification handled
    * ✅ Settlement execution managed
    * ✅ Gas fees covered
    * ✅ Error handling built-in
    * ✅ Simple integration (x402 middleware)
    * ✅ Pre-settlement fee collection (no free service)

    **Cost:** \$0.01 per settlement for all infrastructure, collected pre-settlement.
  </Accordion>
</AccordionGroup>

***

## Pre-Settlement Deep Dive

<AccordionGroup>
  <Accordion title="What exactly is pre-settlement fee collection?">
    **Definition:** The facilitator collects the \$0.01 fee from the merchant's approved USDC balance BEFORE executing the customer → merchant payment.

    **Order of operations:**

    ```
    1. Customer submits payment authorization
    2. Facilitator verifies authorization
    3. ✅ Facilitator collects $0.01 from merchant (pre-settlement)
    4. ✅ Facilitator executes customer → merchant payment
    ```

    **Critical:** If step 3 fails, step 4 never happens. Customer is never charged.
  </Accordion>

  <Accordion title="What are the benefits of pre-settlement?">
    **For customers:**

    * ✅ Never charged if fee collection fails
    * ✅ Protected from failed settlement attempts

    **For facilitator:**

    * ✅ Guaranteed payment for service
    * ✅ No free service exploitation
    * ✅ Sustainable business model

    **For merchants:**

    * ✅ Transparent fee structure
    * ✅ Predictable costs
    * ⚠️ Pay for settlement attempts (fair trade for preventing exploitation)
  </Accordion>

  <Accordion title="What happens in each scenario?">
    **Scenario 1: Everything succeeds**

    ```
    1. Fee collection: ✅ Success ($0.01 from merchant)
    2. Settlement: ✅ Success ($0.02 to merchant from customer)
    Result: Merchant pays $0.01, receives $0.02, net +$0.01
    ```

    **Scenario 2: Fee collection fails**

    ```
    1. Fee collection: ❌ Failed (insufficient allowance/balance)
    2. Settlement: 🚫 Blocked (never attempted)
    Result: Customer not charged, merchant not charged
    ```

    **Scenario 3: Fee succeeds, settlement fails**

    ```
    1. Fee collection: ✅ Success ($0.01 from merchant)
    2. Settlement: ❌ Failed (expired authorization, etc.)
    Result: Merchant pays $0.01 for the attempt, customer not charged
    ```

    **Why scenario 3 is fair:** Merchant received verification and settlement attempt services worth \$0.01.
  </Accordion>
</AccordionGroup>

***

## Get Started

No signup required - just start building:

```bash theme={null}
# 1. Approve facilitator
EVM_PRIVATE_KEY=0x... node approve-facilitator.mjs

# 2. Add x402 middleware
npm install @x402/express @x402/evm @x402/core

# 3. Start accepting payments
npm start
```

<Info>
  **Questions not answered here?** Check the [x402 Integration Guide](/x402-integration) or contact [support@0xmeta.ai](mailto:support@0xmeta.ai)

  **Remember:** Pre-settlement fee collection means the \$0.01 fee is collected BEFORE executing the customer payment. This protects customers and prevents free service exploitation.
</Info>