Demo Mode

API Documentation

Complete reference documentation for the FinAegis REST API with interactive examples and code samples.

Getting Started

The FinAegis API provides programmatic access to our multi-asset banking platform spanning 42 DDD domains with over 1,200 routes. Our API is organized around REST principles with predictable, resource-oriented URLs. Domains include core banking, CrossChain bridging, DeFi protocols, RegTech compliance, Mobile Payment, Partner BaaS, and AI-powered queries.

Base URL

https://api.finaegis.org/v2

Response Format

All API responses are returned in JSON format with a consistent structure:

{
  "data": { ... },          // Main response data
  "meta": { ... },          // Metadata (pagination, etc.)
  "links": { ... },         // Related links
  "errors": [ ... ]         // Error details (if any)
}

Authentication

The FinAegis API uses API keys to authenticate requests. You can generate and manage your API keys in your dashboard.

Creating API Keys

  1. Log in to your FinAegis account
  2. Navigate to API Keys in your dashboard
  3. Click "Create New Key" and configure permissions
  4. Copy the generated key immediately (it won't be shown again)

API Key Authentication

Include your API key in the Authorization header:

curl -H "Authorization: Bearer fak_your_api_key_here" \
     -H "Content-Type: application/json" \
     https://api.finaegis.org/v2/accounts

API Key Security

  • Permissions: Grant only the minimum required permissions (read, write, delete)
  • IP Whitelist: Restrict API key usage to specific IP addresses
  • Expiration: Set expiration dates for temporary keys
  • Rotation: Regularly rotate your API keys
  • Storage: Never commit API keys to version control

Sandbox vs Production

Use these base URLs for testing and production:

  • Sandbox: https://api-sandbox.finaegis.org/v2
  • Production: https://api.finaegis.org/v2

Accounts

List Accounts

GET /accounts

Retrieve a list of all accounts for the authenticated user.

curl -H "Authorization: Bearer your_api_key" \
     https://api.finaegis.org/v2/accounts

Get Account Details

GET /accounts/{uuid}

Retrieve detailed information about a specific account.

curl -H "Authorization: Bearer your_api_key" \
     https://api.finaegis.org/v2/accounts/acct_1234567890

Get Account Balances

GET /accounts/{uuid}/balances

Get current balances for all assets in an account.

{
  "data": {
    "account_uuid": "acct_1234567890",
    "balances": [
      {
        "asset_code": "USD",
        "available_balance": "1500.00",
        "reserved_balance": "0.00",
        "total_balance": "1500.00"
      },
      {
        "asset_code": "EUR", 
        "available_balance": "1200.50",
        "reserved_balance": "50.00",
        "total_balance": "1250.50"
      }
    ],
    "summary": {
      "total_assets": 2,
      "total_usd_equivalent": "2,850.75"
    }
  }
}

Transactions

List Transactions

GET /transactions

Get a paginated list of all transactions.

Query Parameters:

  • page - Page number (default: 1)
  • per_page - Items per page (default: 20, max: 100)
  • asset_code - Filter by asset code
  • status - Filter by status
curl -H "Authorization: Bearer your_api_key" \
     "https://api.finaegis.org/v2/transactions?page=1&per_page=20"

Deposit Funds

POST /accounts/{uuid}/deposit

Deposit funds into an account.

curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "500.00",
    "asset_code": "USD",
    "reference": "Initial deposit"
  }' \
  https://api.finaegis.org/v2/accounts/acct_1234567890/deposit

Withdraw Funds

POST /accounts/{uuid}/withdraw

Withdraw funds from an account.

curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "100.00",
    "asset_code": "USD",
    "reference": "ATM withdrawal"
  }' \
  https://api.finaegis.org/v2/accounts/acct_1234567890/withdraw

Transfers

Create Transfer

POST /transfers

Create a new transfer between accounts.

curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from_account": "acct_1234567890",
    "to_account": "acct_0987654321", 
    "amount": "100.00",
    "asset_code": "USD",
    "reference": "Payment for services",
    "workflow_enabled": true
  }' \
  https://api.finaegis.org/v2/transfers

Get Transfer History

GET /accounts/{uuid}/transfers

Get transfer history for a specific account.

curl -H "Authorization: Bearer your_api_key" \
     https://api.finaegis.org/v2/accounts/acct_1234567890/transfers

Global Currency Unit (GCU)

The GCU endpoints provide access to real-time data about the Global Currency Unit, including its composition, value history, and governance information.

Get GCU Information

GET /v2/gcu

Get current information about the Global Currency Unit including composition and value.

curl -H "Authorization: Bearer your_api_key" \
     https://api.finaegis.org/v2/gcu

Get Real-time GCU Composition

GET /v2/gcu/composition

Get detailed real-time composition data including current weights, values, and recent changes for each component asset.

curl -H "Authorization: Bearer your_api_key" \
     https://api.finaegis.org/v2/gcu/composition

Response Example:

{
  "data": {
    "basket_code": "GCU",
    "last_updated": "2024-01-15T10:30:00Z",
    "total_value_usd": 1.0975,
    "composition": [
      {
        "asset_code": "USD",
        "asset_name": "US Dollar",
        "asset_type": "fiat",
        "weight": 0.35,
        "current_price_usd": 1.0000,
        "value_contribution_usd": 0.3500,
        "percentage_of_basket": 31.89,
        "24h_change": 0.00,
        "7d_change": 0.00
      },
      {
        "asset_code": "EUR",
        "asset_name": "Euro", 
        "asset_type": "fiat",
        "weight": 0.30,
        "current_price_usd": 1.0850,
        "value_contribution_usd": 0.3255,
        "percentage_of_basket": 29.68,
        "24h_change": 0.15,
        "7d_change": -0.23
      }
    ],
    "rebalancing": {
      "frequency": "quarterly",
      "last_rebalanced": "2024-01-01T00:00:00Z",
      "next_rebalance": "2024-04-01T00:00:00Z",
      "automatic": true
    },
    "performance": {
      "24h_change_usd": 0.0025,
      "24h_change_percent": 0.23,
      "7d_change_usd": -0.0050,
      "7d_change_percent": -0.45,
      "30d_change_usd": 0.0175,
      "30d_change_percent": 1.62
    }
  }
}

Get GCU Value History

GET /v2/gcu/value-history

Get historical value data for the Global Currency Unit.

Query Parameters:

  • period - Time period: 24h, 7d, 30d, 90d, 1y, all (default: 30d)
  • interval - Data interval: hourly, daily, weekly, monthly (default: daily)
curl -H "Authorization: Bearer your_api_key" \
     "https://api.finaegis.org/v2/gcu/value-history?period=7d&interval=hourly"

Democratic Voting System

The GCU voting system allows token holders to participate in monthly governance votes to optimize the currency basket composition.

List Voting Proposals

GET /v2/gcu/voting/proposals

Get all voting proposals with optional status filtering.

Query Parameters:

  • status - Filter by status: active, upcoming, past (optional)
curl -H "Authorization: Bearer your_api_key" \
     "https://api.finaegis.org/v2/gcu/voting/proposals?status=active"

Get Proposal Details

GET /v2/gcu/voting/proposals/{id}

Get detailed information about a specific voting proposal.

curl -H "Authorization: Bearer your_api_key" \
     https://api.finaegis.org/v2/gcu/voting/proposals/123

Cast Vote

POST /v2/gcu/voting/proposals/{id}/vote
Requires Authentication

Cast your vote on a proposal. Voting power is determined by your GCU balance.

Request Body:

{
  "vote": "for"  // Options: "for", "against", "abstain"
}
curl -X POST \
     -H "Authorization: Bearer your_api_key" \
     -H "Content-Type: application/json" \
     -d '{"vote": "for"}' \
     https://api.finaegis.org/v2/gcu/voting/proposals/123/vote

Get My Voting History

GET /v2/gcu/voting/my-votes
Requires Authentication

Get your voting history across all proposals.

curl -H "Authorization: Bearer your_api_key" \
     https://api.finaegis.org/v2/gcu/voting/my-votes

Baskets

Baskets are multi-asset currency units that can be composed and decomposed. The GCU is our primary basket.

List Baskets

GET /baskets

Get a list of all available baskets.

curl -H "Authorization: Bearer your_api_key" \
     https://api.finaegis.org/v2/baskets

Get Basket Details

GET /baskets/{code}

Get detailed information about a specific basket.

curl -H "Authorization: Bearer your_api_key" \
     https://api.finaegis.org/v2/baskets/GCU

Compose Basket

POST /accounts/{uuid}/baskets/compose

Convert individual assets into basket units.

curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "basket_code": "GCU",
    "amount": "100.00"
  }' \
  https://api.finaegis.org/v2/accounts/acct_123/baskets/compose

Decompose Basket

POST /accounts/{uuid}/baskets/decompose

Convert basket units back to individual assets.

curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "basket_code": "GCU",
    "amount": "50.00"
  }' \
  https://api.finaegis.org/v2/accounts/acct_123/baskets/decompose

Webhooks

Webhooks allow you to receive real-time notifications when events occur in your FinAegis account.

List Webhook Events

GET /webhooks/events

Get a list of all available webhook event types.

curl -H "Authorization: Bearer your_api_key" \
     https://api.finaegis.org/v2/webhooks/events

Create Webhook

POST /webhooks

Create a new webhook endpoint.

curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhook",
    "events": ["transaction.created", "transfer.completed"],
    "description": "Main webhook endpoint"
  }' \
  https://api.finaegis.org/v2/webhooks

List Webhooks

GET /webhooks

Get all webhook endpoints for your account.

curl -H "Authorization: Bearer your_api_key" \
     https://api.finaegis.org/v2/webhooks

Get Webhook Deliveries

GET /webhooks/{id}/deliveries

Get delivery history for a specific webhook.

curl -H "Authorization: Bearer your_api_key" \
     https://api.finaegis.org/v2/webhooks/webhook_123/deliveries

CrossChain API

The CrossChain API enables multi-chain operations including bridge transfers via Wormhole, LayerZero, and Axelar protocols. Compare bridge fees, execute cross-chain swaps, and track portfolios across multiple blockchains.

7 routes · View in Swagger UI

Initiate Bridge Transfer

POST /v2/crosschain/bridge

Initiate a cross-chain bridge transfer through Wormhole, LayerZero, or Axelar.

curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "source_chain": "ethereum",
    "destination_chain": "polygon",
    "token": "USDC",
    "amount": "1000.00",
    "protocol": "wormhole"
  }' \
  https://api.finaegis.org/v2/crosschain/bridge

Compare Bridge Fees

GET /v2/crosschain/bridge/fees

Compare fees and estimated times across all supported bridge protocols for a given route.

curl -H "Authorization: Bearer your_api_key" \
     "https://api.finaegis.org/v2/crosschain/bridge/fees?from=ethereum&to=arbitrum&token=USDC&amount=5000"

Cross-Chain Swap

POST /v2/crosschain/swap

Execute a token swap that bridges and swaps in a single atomic operation.

curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "source_chain": "ethereum",
    "destination_chain": "polygon",
    "from_token": "ETH",
    "to_token": "MATIC",
    "amount": "1.5",
    "slippage_bps": 50
  }' \
  https://api.finaegis.org/v2/crosschain/swap

Multi-Chain Portfolio

GET /v2/crosschain/portfolio

Retrieve an aggregated portfolio view across all supported chains.

curl -H "Authorization: Bearer your_api_key" \
     https://api.finaegis.org/v2/crosschain/portfolio

DeFi API

The DeFi API provides access to decentralized finance protocols including DEX aggregation (Uniswap, Curve), lending (Aave), staking (Lido), yield optimization, and flash loan execution.

8 routes · View in Swagger UI

Get Swap Quote

GET /v2/defi/swap/quote

Get the best swap quote aggregated across Uniswap, Curve, and other supported DEXes.

curl -H "Authorization: Bearer your_api_key" \
     "https://api.finaegis.org/v2/defi/swap/quote?from=ETH&to=USDC&amount=2.0&chain=ethereum"

Execute Swap

POST /v2/defi/swap/execute

Execute a token swap through the optimal DEX route.

curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from_token": "ETH",
    "to_token": "USDC",
    "amount": "2.0",
    "slippage_bps": 50,
    "chain": "ethereum"
  }' \
  https://api.finaegis.org/v2/defi/swap/execute

DeFi Portfolio Positions

GET /v2/defi/portfolio

Retrieve all DeFi positions including lending deposits, staking, liquidity pools, and yield farming.

curl -H "Authorization: Bearer your_api_key" \
     https://api.finaegis.org/v2/defi/portfolio

Flash Loan

POST /v2/defi/flash-loan

Execute a flash loan with a sequence of operations that must complete atomically.

curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "USDC",
    "amount": "100000.00",
    "operations": [
      {"type": "swap", "from": "USDC", "to": "ETH", "dex": "uniswap"},
      {"type": "swap", "from": "ETH", "to": "USDC", "dex": "curve"}
    ]
  }' \
  https://api.finaegis.org/v2/defi/flash-loan

RegTech API

The RegTech API provides regulatory compliance capabilities including MiFID II transaction reporting, MiCA crypto-asset compliance, Travel Rule enforcement for cross-border transfers, and jurisdiction-specific adapter configuration.

12 routes · View in Swagger UI

Submit MiFID II Report

POST /v2/regtech/mifid/reports

Submit a MiFID II transaction report to the configured National Competent Authority.

curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "txn_abc123",
    "report_type": "transaction",
    "jurisdiction": "EU"
  }' \
  https://api.finaegis.org/v2/regtech/mifid/reports

MiCA Compliance Check

POST /v2/regtech/mica/check

Run a MiCA compliance validation against a crypto-asset or token issuance.

curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "asset_type": "e-money-token",
    "issuer_id": "issuer_xyz",
    "whitepaper_hash": "sha256:abc..."
  }' \
  https://api.finaegis.org/v2/regtech/mica/check

Travel Rule Transfer

POST /v2/regtech/travel-rule/transfers

Submit originator and beneficiary information for FATF Travel Rule compliance on cross-border transfers.

curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "transfer_id": "xfer_789",
    "originator": {"name": "Alice Smith", "account": "acc_123"},
    "beneficiary": {"name": "Bob Jones", "vasp_id": "vasp_456"},
    "amount": "15000.00",
    "currency": "USDC"
  }' \
  https://api.finaegis.org/v2/regtech/travel-rule/transfers

Compliance Status

GET /v2/regtech/status

Get overall compliance status across all active regulatory frameworks.

curl -H "Authorization: Bearer your_api_key" \
     https://api.finaegis.org/v2/regtech/status

Mobile Payment API

The Mobile Payment API powers the FinAegis mobile wallet experience with payment intents, digital receipts, activity feeds, receive addresses, P2P transfers, passkey authentication, and biometric JWT sessions.

25+ routes · View in Swagger UI

Create Payment Intent

POST /v2/mobile/payments/intents

Create a new payment intent for mobile wallet transactions.

curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "25.00",
    "currency": "USD",
    "recipient": "user_456",
    "description": "Coffee payment"
  }' \
  https://api.finaegis.org/v2/mobile/payments/intents

Activity Feed

GET /v2/mobile/activity

Retrieve the mobile wallet activity feed with payments, transfers, and notifications.

curl -H "Authorization: Bearer your_api_key" \
     "https://api.finaegis.org/v2/mobile/activity?page=1&per_page=20"

P2P Transfer

POST /v2/mobile/transfers/p2p

Send a peer-to-peer transfer to another mobile wallet user.

curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to_user": "user_789",
    "amount": "50.00",
    "currency": "USD",
    "note": "Dinner split"
  }' \
  https://api.finaegis.org/v2/mobile/transfers/p2p

Passkey Authentication

POST /v2/mobile/auth/passkey/verify

Verify a FIDO2/WebAuthn passkey for passwordless mobile authentication.

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "credential_id": "cred_abc",
    "authenticator_data": "base64...",
    "client_data_json": "base64...",
    "signature": "base64..."
  }' \
  https://api.finaegis.org/v2/mobile/auth/passkey/verify

Partner / BaaS API

The Partner BaaS (Banking-as-a-Service) API enables third-party partners to provision tenants, generate branded SDKs, configure white-label deployments, and manage their partner integrations. Requires a Partner API key (fpk_ prefix) in addition to standard authentication.

24 routes · View in Swagger UI

Provision Tenant

POST /v2/partner/tenants
Partner Key Required

Provision a new tenant for a BaaS partner with isolated data and configuration.

curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "X-Partner-Key: fpk_your_partner_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Bank",
    "plan": "enterprise",
    "domain": "acme.finaegis.io"
  }' \
  https://api.finaegis.org/v2/partner/tenants

Generate SDK

POST /v2/partner/sdk/generate
Partner Key Required

Generate a branded SDK package for the partner's platform and language.

curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "X-Partner-Key: fpk_your_partner_key" \
  -H "Content-Type: application/json" \
  -d '{
    "language": "javascript",
    "branding": {"name": "AcmeSDK", "color": "#3B82F6"},
    "modules": ["accounts", "transfers", "payments"]
  }' \
  https://api.finaegis.org/v2/partner/sdk/generate

White-Label Configuration

PUT /v2/partner/config/whitelabel
Partner Key Required

Update white-label branding, theming, and feature toggles for the partner deployment.

curl -X PUT \
  -H "Authorization: Bearer your_api_key" \
  -H "X-Partner-Key: fpk_your_partner_key" \
  -H "Content-Type: application/json" \
  -d '{
    "logo_url": "https://acme.com/logo.svg",
    "primary_color": "#3B82F6",
    "features": {"defi": true, "crosschain": true, "lending": false}
  }' \
  https://api.finaegis.org/v2/partner/config/whitelabel

List Partner Tenants

GET /v2/partner/tenants
Partner Key Required

List all tenants provisioned under this partner account.

curl -H "Authorization: Bearer your_api_key" \
     -H "X-Partner-Key: fpk_your_partner_key" \
     https://api.finaegis.org/v2/partner/tenants

AI Query API

The AI Query API provides natural language access to transaction data and financial insights. Ask questions in plain English and receive structured, actionable responses.

2 routes · View in Swagger UI

Natural Language Query

POST /v2/ai/query

Submit a natural language question about your transactions, balances, or financial activity.

curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What were my largest transactions last month?",
    "context": {"account_id": "acc_123"}
  }' \
  https://api.finaegis.org/v2/ai/query

AI Query History

GET /v2/ai/queries

Retrieve your past AI query history with cached results.

curl -H "Authorization: Bearer your_api_key" \
     https://api.finaegis.org/v2/ai/queries

GraphQL API

Schema-first GraphQL API powered by Lighthouse PHP. Provides queries, mutations, and subscriptions across 34 domain schemas with DataLoader-optimized resolvers and WebSocket-based real-time subscriptions.

34 domain schemas · Queries, Mutations, Subscriptions

Execute GraphQL Query / Mutation

POST /graphql

Execute a GraphQL query or mutation against the unified schema. Supports all 34 domain schemas including Account, AgentProtocol, Basket, Batch, CardIssuance, Cgo, Compliance, CrossChain, DeFi, Exchange, FinancialInstitution, Product, Regulatory, User, Wallet, and more.

curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "{ accounts(first: 10) { data { id name currency balance { available total } } } }"
  }' \
  https://api.finaegis.org/graphql

Example Query:

query {
  accounts(first: 10) {
    data {
      id
      name
      currency
      balance {
        available
        total
      }
    }
    paginatorInfo {
      total
      currentPage
      lastPage
    }
  }
}

GraphQL Playground

GET /graphql-playground

Interactive GraphQL explorer with schema introspection, auto-complete, and query history. Use this to explore available types, queries, mutations, and subscriptions.

# Open in your browser
https://api.finaegis.org/graphql-playground

Available Subscriptions

Real-time WebSocket subscriptions are available for the following events:

  • accountUpdated(id: ID!) - Account balance and status changes
  • transactionCreated(accountId: ID!) - New transactions on an account
  • transferCompleted(id: ID!) - Transfer completion notifications
  • orderMatched(pair: String!) - Exchange order match events

Event Streaming & Live Dashboard

Real-time event streaming via Redis Streams with a live metrics dashboard. Monitor system health, domain status, event throughput, stream connectivity, and projector lag across all event-sourced domains.

5 endpoints · Redis Streams · Real-time Metrics

System Metrics

GET /v1/live-dashboard/metrics

Retrieve aggregated system metrics including event counts, processing rates, error rates, and uptime statistics.

curl -H "Authorization: Bearer your_api_key" \
     https://api.finaegis.org/v1/live-dashboard/metrics

Domain Health

GET /v1/live-dashboard/domain-health

Get health status for each event-sourced domain including event store connectivity, projector status, and recent error counts.

curl -H "Authorization: Bearer your_api_key" \
     https://api.finaegis.org/v1/live-dashboard/domain-health

Event Throughput

GET /v1/live-dashboard/event-throughput

Monitor real-time event throughput rates per domain and aggregate, including events per second and processing latency.

curl -H "Authorization: Bearer your_api_key" \
     https://api.finaegis.org/v1/live-dashboard/event-throughput

Stream Status

GET /v1/live-dashboard/stream-status

Check Redis Streams connectivity, consumer group status, pending message counts, and stream memory usage.

curl -H "Authorization: Bearer your_api_key" \
     https://api.finaegis.org/v1/live-dashboard/stream-status

Projector Lag

GET /v1/live-dashboard/projector-lag

Monitor projector lag across all event-sourced domains showing how far behind each read model projector is from the latest events.

curl -H "Authorization: Bearer your_api_key" \
     https://api.finaegis.org/v1/live-dashboard/projector-lag

x402 Protocol API

The x402 Protocol enables HTTP-native micropayments using USDC on Base. Monetize any API endpoint by returning HTTP 402 responses with payment requirements. Supports AI agent autonomous payments, spending limits, and multi-network settlement.

15+ endpoints · View in Swagger UI

Protocol Status

GET /v2/x402/status

Get the current x402 protocol status including supported networks, assets, and facilitator connectivity.

curl -H "Authorization: Bearer your_api_key" \
     https://api.finaegis.org/v2/x402/status

Supported Networks

GET /v2/x402/supported

List all supported blockchain networks and payment assets for x402 settlement.

curl -H "Authorization: Bearer your_api_key" \
     https://api.finaegis.org/v2/x402/supported

Monetized Endpoints

POST /v2/x402/endpoints

Register an API endpoint for x402 monetization with pricing configuration.

curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/v2/premium/data",
    "price_usd_cents": 100,
    "network": "eip155:8453",
    "asset": "USDC",
    "description": "Premium market data"
  }' \
  https://api.finaegis.org/v2/x402/endpoints

Payment History

GET /v2/x402/payments

Retrieve payment history and settlement status for x402 transactions.

curl -H "Authorization: Bearer your_api_key" \
     "https://api.finaegis.org/v2/x402/payments?page=1&per_page=20"

Spending Limits

GET /v2/x402/spending-limits

View and manage spending limits for automated x402 payments including AI agent budgets.

curl -H "Authorization: Bearer your_api_key" \
     https://api.finaegis.org/v2/x402/spending-limits

Handling 402 Responses

When a client hits a monetized endpoint without payment, it receives an HTTP 402 with payment requirements in headers:

HTTP/1.1 402 Payment Required
X-Payment-Required: true
X-Payment-Network: eip155:8453
X-Payment-Asset: USDC
X-Payment-Amount: 0.01
X-Payment-Receiver: 0x...
X-Payment-Facilitator: https://x402.org/facilitator

JavaScript Client Example:

const response = await fetch('https://api.finaegis.org/v2/premium/data', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});

if (response.status === 402) {
  const paymentInfo = {
    network: response.headers.get('X-Payment-Network'),
    asset: response.headers.get('X-Payment-Asset'),
    amount: response.headers.get('X-Payment-Amount'),
    receiver: response.headers.get('X-Payment-Receiver'),
  };

  // Sign and submit payment, then retry with proof
  const proof = await signPayment(paymentInfo);
  const paid = await fetch('https://api.finaegis.org/v2/premium/data', {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'X-Payment-Signature': proof.signature,
      'X-Payment-Payload': proof.payload,
    }
  });
  const data = await paid.json(); // 200 + data
}

Quick Links

Platform API Areas

OpenAPI Specification

Download the OpenAPI specification file or view it in your preferred API client.

Download OpenAPI JSON Interactive API Explorer

Import the JSON file into Postman, Insomnia, or any OpenAPI-compatible tool