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

bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
# 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

bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
# 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

bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
# 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

bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
# 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"
}
Large exports are processed asynchronously. Poll the export endpoint or set up a webhook to be notified when the export is ready.
Next: Manage external connections with the Integrations API.