API Documentation

Complete reference for ARIA Oracle fraud detection API

📋 Table of Contents

🚀 Getting Started

The ARIA Oracle API provides real-time fraud detection with cryptographic proofs. All API requests must be authenticated using an API key.

Base URL

https://api.ariaoracle.com/v1

Quick Start

curl -X POST https://api.ariaoracle.com/v1/fraud/analyze \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "txn_123456",
    "amount": 299.99,
    "currency": "USD",
    "user_id": "user_abc123",
    "email": "user@example.com"
  }'

🔐 Authentication

All API requests require an API key passed in the X-API-Key header.

Get Your API Key

POST /auth/api-key

Request Headers

Authorization: Bearer {your_access_token}
Content-Type: application/json

Request Body

{
  "name": "production-key",
  "expires_days": 90
}

Response

{
  "api_key": "aria_live_1234567890abcdef",
  "name": "production-key",
  "created_at": "2025-11-16T10:30:00Z",
  "expires_at": "2026-02-14T10:30:00Z"
}

🛡️ Fraud Detection API

Analyze Transaction

Submit a transaction for fraud analysis and receive a decision with cryptographic proof.

POST /v1/fraud/analyze

Request Headers

X-API-Key: aria_live_1234567890abcdef
Content-Type: application/json

Request Body

{
  "transaction_id": "txn_123456",
  "amount": 299.99,
  "currency": "USD",
  "user_id": "user_abc123",
  "email": "user@example.com",
  "ip_address": "203.0.113.42",
  "device_fingerprint": "fp_xyz789",
  "billing_address": {
    "street": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94102",
    "country": "US"
  },
  "metadata": {
    "product_id": "prod_456",
    "category": "electronics"
  }
}

Response (200 OK)

{
  "decision": "approved",
  "confidence": 0.987,
  "risk_score": 12,
  "transaction_id": "txn_123456",
  "decision_id": "dec_789xyz",
  "proof": {
    "hash": "9f2c4a7b8d3e1a6f0c9d2b7e4a5c8d9f0e1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c",
    "signature": "0x1234567890abcdef...",
    "blockchain_anchor": "ethereum:19876543",
    "verification_url": "https://etherscan.io/block/19876543"
  },
  "reasons": [
    "User has established payment history",
    "IP address matches billing location",
    "Device fingerprint recognized"
  ],
  "timestamp": "2025-11-16T10:35:22Z"
}

Response (Declined Transaction)

{
  "decision": "declined",
  "confidence": 0.923,
  "risk_score": 87,
  "transaction_id": "txn_123456",
  "decision_id": "dec_789xyz",
  "proof": {
    "hash": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2",
    "signature": "0xabcdef1234567890...",
    "blockchain_anchor": "ethereum:19876544",
    "verification_url": "https://etherscan.io/block/19876544"
  },
  "reasons": [
    "Suspicious IP address (VPN detected)",
    "Email domain flagged in fraud database",
    "Unusual transaction amount for user"
  ],
  "timestamp": "2025-11-16T10:35:23Z"
}

🔔 Webhooks

Configure webhooks to receive real-time notifications about fraud decisions.

Configure Webhook

POST /webhooks

Request Body

{
  "url": "https://your-domain.com/webhooks/aria",
  "events": ["decision.created", "decision.updated"],
  "secret": "whsec_1234567890abcdef"
}

Webhook Payload

{
  "event": "decision.created",
  "timestamp": "2025-11-16T10:35:22Z",
  "data": {
    "decision": "declined",
    "transaction_id": "txn_123456",
    "decision_id": "dec_789xyz",
    "risk_score": 87,
    "proof_hash": "a1b2c3d4e5f6..."
  }
}

⚠️ Error Handling

The API uses standard HTTP status codes and returns error details in JSON format.

Error Response Format

{
  "error": {
    "code": "invalid_request",
    "message": "Missing required field: transaction_id",
    "param": "transaction_id",
    "type": "validation_error"
  }
}

Common Error Codes

Code Description
400 Bad Request - Invalid parameters
401 Unauthorized - Invalid API key
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error