Your App  →  AgnicPay /api/merchant/charge  →  User's Wallet
                         ↓
              Settlement to Your Wallet

POST https://api.agnic.ai/api/merchant/charge

{
  "amount": "100000",
  "reference": "order_123",
  "description": "Plaid API call"
}

{
  "success": true,
  "transactionHash": "0x...",
  "amountUsd": 0.10,
  "network": "base",
  "merchantId": "did:privy:...",
  "merchantWallet": "0x...",
  "reference": "order_123",
  "explorerUrl": "https://basescan.org/tx/0x...",
  "request_id": "req_..."
}

{
  "error": "missing_merchant_id",
  "message": "X-Merchant-Id header is required"
}

{
  "error": "invalid_amount",
  "message": "amount must be a positive integer (USDC atomic units)"
}

{
  "error": "daily_limit_exceeded",
  "message": "Daily limit exceeded. Spent: $5.00, Limit: $10.00",
  "spent": 5.0,
  "limit": 10.0
}

{
  "error": "network_not_allowed",
  "message": "Base network is required for merchant charges but not allowed by your token"
}

import requests
 
def charge_user(user_token: str, amount_cents: int, reference: str = None):
    """
    Charge a user for a resource.
 
    Args:
        user_token: The user's AgnicPay API token
        amount_cents: Amount in cents (e.g., 10 = $0.10)
        reference: Your tracking reference
    """
    # Convert cents to atomic units (6 decimals)
    amount_atomic = amount_cents * 10000  # 10 cents = 100000 atomic
 
    response = requests.post(
        "https://api.agnic.ai/api/merchant/charge",
        headers={
            "X-Agnic-Token": user_token,
            "X-Merchant-Id": "did:privy:your-merchant-id",
            "X-Merchant-Wallet": "0xYourWalletAddress",
            "Content-Type": "application/json",
        },
        json={
            "amount": str(amount_atomic),
            "reference": reference,
            "description": "API usage charge",
        }
    )
 
    return response.json()
 
# Example: Charge $0.05 for a Plaid API call
result = charge_user(
    user_token="agnic_tok_USER_TOKEN",
    amount_cents=5,
    reference="plaid_txn_123"
)
 
if result.get("success"):
    print(f"Charged! TX: {result['transactionHash']}")
else:
    print(f"Error: {result.get('error')}")

async function chargeUser(
  userToken: string,
  amountCents: number,
  reference?: string
): Promise<ChargeResult> {
  // Convert cents to atomic units (6 decimals)
  const amountAtomic = amountCents * 10000;
 
  const response = await fetch('https://api.agnic.ai/api/merchant/charge', {
    method: 'POST',
    headers: {
      'X-Agnic-Token': userToken,
      'X-Merchant-Id': 'did:privy:your-merchant-id',
      'X-Merchant-Wallet': '0xYourWalletAddress',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      amount: amountAtomic.toString(),
      reference,
      description: 'API usage charge',
    }),
  });
 
  return response.json();
}
 
// Example: Charge $0.10 for file processing
const result = await chargeUser(userToken, 10, 'file_proc_456');
 
if (result.success) {
  console.log(`Charged! TX: ${result.transactionHash}`);
  // Proceed with file processing
} else {
  console.error(`Charge failed: ${result.error}`);
}

curl -X POST https://api.agnic.ai/api/merchant/charge \
  -H "Content-Type: application/json" \
  -H "X-Agnic-Token: agnic_tok_USER_TOKEN" \
  -H "X-Merchant-Id: did:privy:your-merchant-id" \
  -H "X-Merchant-Wallet: 0xYourWalletAddress" \
  -d '{
    "amount": "100000",
    "reference": "order_123",
    "description": "Plaid API call"
  }'

def link_bank_account(user_token: str, user_id: str):
    # 1. Charge the user first
    charge = charge_user(
        user_token=user_token,
        amount_cents=50,  # $0.50 per link
        reference=f"plaid_link_{user_id}"
    )
 
    if not charge.get("success"):
        raise Exception(f"Payment failed: {charge.get('error')}")
 
    # 2. Only proceed if payment succeeded
    plaid_response = plaid_client.link_token_create(...)
 
    return {
        "link_token": plaid_response.link_token,
        "charge_tx": charge["transactionHash"]
    }

def process_file(user_token: str, file_size_mb: int, file_id: str):
    # Price: $0.01 per MB
    amount_cents = file_size_mb * 1
 
    charge = charge_user(
        user_token=user_token,
        amount_cents=amount_cents,
        reference=f"file_{file_id}"
    )
 
    if charge.get("success"):
        # Process the file
        result = process_file_internal(file_id)
        return {"status": "processed", "tx": charge["transactionHash"]}
    else:
        return {"status": "payment_failed", "error": charge.get("error")}

def query_data(user_token: str, query: str, query_id: str):
    # Estimate cost based on query complexity
    estimated_cost_cents = estimate_query_cost(query)
 
    charge = charge_user(
        user_token=user_token,
        amount_cents=estimated_cost_cents,
        reference=f"query_{query_id}"
    )
 
    if charge.get("success"):
        results = execute_query(query)
        return {"data": results, "cost": estimated_cost_cents / 100}
    else:
        raise PaymentError(charge.get("message"))

def safe_charge(user_token: str, amount_cents: int, reference: str):
    try:
        result = charge_user(user_token, amount_cents, reference)
 
        if result.get("success"):
            return {"ok": True, "tx": result["transactionHash"]}
 
        error = result.get("error")
 
        if error == "daily_limit_exceeded":
            return {"ok": False, "reason": "Daily spending limit reached"}
        elif error == "amount_exceeds_limit":
            return {"ok": False, "reason": "Amount too high for this token"}
        elif error == "network_not_allowed":
            return {"ok": False, "reason": "Token doesn't allow Base network"}
        else:
            return {"ok": False, "reason": result.get("message", "Unknown error")}
 
    except Exception as e:
        return {"ok": False, "reason": str(e)}