Hyperfold AI

Finance API

Manage payments, wallets, transactions, and financial reporting.

Overview

The Finance API provides access to all payment and financial data in your Hyperfold project, including payment processing, agent wallets, transaction history, and financial reporting.

ResourceDescription
PaymentsPayment records, refunds, disputes
WalletsAgent payment wallets and funding
TransactionsComplete transaction ledger
ReportsFinancial summaries and exports

Payments

# GET /v1/finance/payments
# List payment records
curl -X GET "https://api.hyperfold.io/v1/finance/payments?status=succeeded&since=2025-01-01&limit=50" \
  -H "Authorization: Bearer hf_live_xxx" \
  -H "X-Project-ID: proj_acme"
# Response
{
  "data": [
    {
      "id": "pay_abc123",
      "order_id": "ord_xyz789",
      "amount": 175.37,
      "currency": "USD",
      "status": "succeeded",
      "provider": "stripe",
      "provider_id": "pi_stripe_xxx",
      "method": "card",
      "card_last4": "4242",
      "customer_id": "cust_123",
      "created_at": "2025-01-20T10:00:00Z"
    }
  ],
  "meta": {
    "total": 4521,
    "total_amount": 792450.00
  }
}
# GET /v1/finance/payments/:id
# Get payment details
curl -X GET https://api.hyperfold.io/v1/finance/payments/pay_abc123 \
  -H "Authorization: Bearer hf_live_xxx"
# POST /v1/finance/payments/:id/refund
# Refund a payment
curl -X POST https://api.hyperfold.io/v1/finance/payments/pay_abc123/refund \
  -H "Authorization: Bearer hf_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50.00,
    "reason": "customer_request",
    "notify_customer": true
  }'

Payment Statuses

StatusDescription
pendingPayment initiated, awaiting processing
processingBeing processed by payment provider
succeededPayment completed successfully
failedPayment failed
refundedFully refunded
partially_refundedPartially refunded

Wallets

# GET /v1/finance/wallets
# List agent wallets
curl -X GET https://api.hyperfold.io/v1/finance/wallets \
  -H "Authorization: Bearer hf_live_xxx" \
  -H "X-Project-ID: proj_acme"
# Response
{
  "data": [
    {
      "id": "wal_xyz789",
      "agent_id": "agent_neg_001",
      "agent_name": "sales-negotiator",
      "currency": "USD",
      "balance": {
        "available": 4250.00,
        "pending": 350.00,
        "reserved": 0.00
      },
      "limits": {
        "daily_limit": 10000.00,
        "daily_used": 2150.00
      },
      "status": "active"
    }
  ]
}
# POST /v1/finance/wallets
# Create a new wallet
curl -X POST https://api.hyperfold.io/v1/finance/wallets \
  -H "Authorization: Bearer hf_live_xxx" \
  -H "X-Project-ID: proj_acme" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_neg_001",
    "currency": "USD",
    "initial_balance": 5000.00,
    "limits": {
      "daily_limit": 10000.00,
      "low_balance_alert": 500.00
    }
  }'
# POST /v1/finance/wallets/:id/fund
# Add funds to wallet
curl -X POST https://api.hyperfold.io/v1/finance/wallets/wal_xyz789/fund \
  -H "Authorization: Bearer hf_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000.00,
    "source": "operating_account"
  }'

Transactions

# GET /v1/finance/transactions
# List all transactions
curl -X GET "https://api.hyperfold.io/v1/finance/transactions?type=sale&since=2025-01-01&limit=100" \
  -H "Authorization: Bearer hf_live_xxx" \
  -H "X-Project-ID: proj_acme"
# Response
{
  "data": [
    {
      "id": "txn_abc123",
      "type": "sale",
      "amount": 162.00,
      "currency": "USD",
      "order_id": "ord_xyz789",
      "payment_id": "pay_abc123",
      "agent_id": "agent_neg_001",
      "wallet_id": "wal_xyz789",
      "customer_id": "cust_123",
      "metadata": {
        "session_id": "sess_abc",
        "negotiation_rounds": 2,
        "discount_applied": "10%"
      },
      "created_at": "2025-01-20T10:00:00Z"
    }
  ],
  "summary": {
    "total_transactions": 4521,
    "total_amount": 792450.00,
    "by_type": {
      "sale": {"count": 4200, "amount": 812000.00},
      "refund": {"count": 321, "amount": -19550.00}
    }
  }
}
# GET /v1/finance/transactions/:id
# Get transaction details including full audit trail
curl -X GET https://api.hyperfold.io/v1/finance/transactions/txn_abc123 \
  -H "Authorization: Bearer hf_live_xxx"

Reports

# GET /v1/finance/reports/summary
# Get financial summary
curl -X GET "https://api.hyperfold.io/v1/finance/reports/summary?period=30d" \
  -H "Authorization: Bearer hf_live_xxx" \
  -H "X-Project-ID: proj_acme"
# Response
{
  "period": {
    "start": "2024-12-21T00:00:00Z",
    "end": "2025-01-20T23:59:59Z"
  },
  "revenue": {
    "gross": 812000.00,
    "refunds": 19550.00,
    "net": 792450.00
  },
  "orders": {
    "total": 4521,
    "average_value": 175.28,
    "conversion_rate": 0.33
  },
  "costs": {
    "llm_tokens": 4800.00,
    "payment_fees": 23773.50,
    "infrastructure": 1200.00
  },
  "margins": {
    "gross_margin": 0.46,
    "net_margin": 0.42
  }
}
# GET /v1/finance/reports/export
# Export financial data
curl -X GET "https://api.hyperfold.io/v1/finance/reports/export?format=csv&type=transactions&since=2025-01-01&until=2025-01-31" \
  -H "Authorization: Bearer hf_live_xxx" \
  -H "X-Project-ID: proj_acme"
# Response: CSV file download
# Or get export URL for async processing:
{
  "export_id": "exp_abc123",
  "status": "processing",
  "download_url": null,
  "estimated_completion": "2025-01-20T10:05:00Z"
}