ALPHA TESTING

🚀 Invest in FinAegis CGO - Continuous Growth Offering

Learn More

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. Our API is organized around REST principles with predictable, resource-oriented URLs.

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

Quick Links

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