Aori Docs

Data & Querying

The Aori protocol provides powerful querying capabilities to retrieve historical order data, track trading activity, and analyze cross-chain swap patterns. This page covers all the tools and types you need to effectively query the Aori API.

Understanding Data Queries

The Aori API maintains a comprehensive database of all orders processed through the protocol. You can query this data to:

  • Track Order History: Monitor your own trading activity across all supported chains
  • Analyze Market Activity: Study trading patterns and volume across different token pairs
  • Build Analytics: Create dashboards and reports for trading performance
  • Monitor Specific Addresses: Track activity for particular wallets or contracts

getOrderDetailsfunction

Get detailed information about a specific order, including its complete event history and current status.

  • Name
    orderHash
    Type
    string
    Description

    The unique identifier of the order

  • Name
    baseUrl
    Type
    string
    Description

    API base URL (defaults to https://api.aori.io)

  • Name
    apiKey
    Type
    string
    Description

    API key for authentication

Returns: OrderDetails

Usage

import { getOrderDetails } from '@aori/aori-ts';

const orderDetails = await getOrderDetails(
  '0x1234567890abcdef1234567890abcdef12345678',
  'https://api.aori.io'
);

console.log('Order status:', orderDetails.status);
console.log('Event history:', orderDetails.events);

Response

{
  orderHash: "0x1234567890abcdef1234567890abcdef12345678",
  offerer: "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b",
  recipient: "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b",
  inputToken: "0x4200000000000000000000000000000000000006",
  inputAmount: "1000000000000000000",
  inputChain: "base",
  inputTokenValueUsd: "3200.00",
  outputToken: "0xaf88d065e77c8cc2239327c5edb3a432268e5831",
  outputAmount: "3200000000",
  outputChain: "arbitrum",
  outputTokenValueUsd: "3200.00",
  startTime: 1703001600,
  endTime: 1703005200,
  srcTx: "0xabc123...",
  dstTx: "0xdef456...",
  timestamp: 1703001780,
  events: [
    {
      eventType: "created",
      timestamp: 1703001600
    },
    {
      eventType: "received",
      timestamp: 1703001650
    },
    {
      eventType: "completed",
      timestamp: 1703001780
    }
  ]
}

queryOrdersfunction

Query historical orders with flexible filtering and pagination options.

  • Name
    baseUrl
    Type
    string
    Description

    API base URL

  • Name
    params
    Type
    QueryOrdersParams
    Description

    Query parameters for filtering

  • Name
    apiKey
    Type
    string
    Description

    API key for authentication

Returns: QueryOrdersResponse

Usage

import { queryOrders } from '@aori/aori-ts';

const response = await queryOrders('https://api.aori.io', {
  offerer: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b',
  inputChain: 'base',
  outputChain: 'arbitrum',
  minTime: 1700000000,
  maxTime: 1700086400,
  limit: 50,
  page: 1
});

Response

{
  orders: [
    {
      orderHash: "0x1234567890abcdef...",
      offerer: "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b",
      inputToken: "0x4200000000000000000000000000000000000006",
      outputToken: "0xaf88d065e77c8cc2239327c5edb3a432268e5831",
      inputAmount: "1000000000000000000",
      outputAmount: "3200000000",
      status: "completed",
      createdAt: 1703001600
    }
  ],
  pagination: {
    currentPage: 1,
    limit: 50,
    totalRecords: 150,
    totalPages: 3
  }
}

Query Types

QueryOrdersParamstype

The QueryOrdersParams interface defines all available filters for querying historical orders. All parameters are optional, allowing you to build flexible queries.

ParameterTypeDescriptionExample
orderHashstringFilter by specific order hash"0x1234567890abcdef..."
offererstringFilter by offerer address"0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b"
recipientstringFilter by recipient address"0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b"
inputTokenstringFilter by input token address"0x4200000000000000000000000000000000000006"
outputTokenstringFilter by output token address"0xaf88d065e77c8cc2239327c5edb3a432268e5831"
inputChainstringFilter by input chain"ethereum", "base", "arbitrum"
outputChainstringFilter by output chain"ethereum", "base", "arbitrum"
minValuestringMinimum USD value filter"1000" (for $1,000+)
maxValuestringMaximum USD value filter"10000" (for under $10,000)
statusstringFilter by order status"pending", "completed", "failed"
minTimenumberStart of time range (Unix timestamp)1703001600
maxTimenumberEnd of time range (Unix timestamp)1703088000
pagenumberPage number for pagination (1-based)1, 2, 3
limitnumberNumber of records per page (max 100)25, 50, 100

Interface Definition

interface QueryOrdersParams {
  orderHash?: string;
  offerer?: string;
  recipient?: string;
  inputToken?: string;
  inputChain?: string;
  outputToken?: string;
  minValue?: string;
  maxValue?: string;
  outputChain?: string;
  srctx?: string;
  dstTx?: string;
  status?: string;
  minTime?: number;
  maxTime?: number;
  page?: number;
  limit?: number;
}

Example Usage

const queryParams: QueryOrdersParams = {
  offerer: "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b",
  inputChain: "ethereum",
  outputChain: "base",
  minTime: 1703001600, // Start of time range
  maxTime: 1703088000, // End of time range
  status: "completed",
  limit: 25,
  page: 1
};

QueryOrdersResponsetype

The QueryOrdersResponse interface contains the results of an order query along with pagination metadata.

  • Name
    orders
    Type
    OrderQueryResult[]
    Description

    Array of orders matching the query criteria

  • Name
    pagination
    Type
    PaginationMetadata
    Description

    Pagination information for the result set

PaginationMetadata

  • Name
    currentPage
    Type
    number
    Description

    Current page number

  • Name
    limit
    Type
    number
    Description

    Number of records per page

  • Name
    totalRecords
    Type
    number
    Description

    Total number of matching records

  • Name
    totalPages
    Type
    number
    Description

    Total number of pages

QueryOrdersResponse Interface

interface QueryOrdersResponse {
  orders: OrderQueryResult[];
  pagination: PaginationMetadata;
}

interface PaginationMetadata {
  currentPage: number;
  limit: number;
  totalRecords: number;
  totalPages: number;
}

Example

const response: QueryOrdersResponse = {
  orders: [
    {
      orderHash: "0x1234567890abcdef...",
      offerer: "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b",
      inputToken: "0xA0b86a33E6441b8C4505B8C4b4d8b4C9db96C4b4",
      outputToken: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      inputAmount: "1000000000000000000",
      outputAmount: "3200000000",
      status: "completed",
      createdAt: 1703001600
    }
  ],
  pagination: {
    currentPage: 1,
    limit: 25,
    totalRecords: 150,
    totalPages: 6
  }
};

Common Query Patterns

Get Detailed Order Information

Order Details and Event History

// Get complete details for a specific order
const orderDetails = await getOrderDetails(
  '0x1234567890abcdef1234567890abcdef12345678'
);

// Check order status
console.log(`Order status: ${orderDetails.events[orderDetails.events.length - 1].eventType}`);

// Track order progression
orderDetails.events.forEach(event => {
  console.log(`${event.eventType} at ${new Date(event.timestamp * 1000).toISOString()}`);
});

// Get transaction links if available
if (orderDetails.srcTx) {
  console.log(`Source tx: https://etherscan.io/tx/${orderDetails.srcTx}`);
}
if (orderDetails.dstTx) {
  console.log(`Destination tx: https://arbiscan.io/tx/${orderDetails.dstTx}`);
}

Query by Address

Track User Activity

// Get all orders for a specific user
const userOrders = await queryOrders('https://api.aori.io', {
  offerer: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b',
  limit: 100
});

// Get orders where user was the recipient
const receivedOrders = await queryOrders('https://api.aori.io', {
  recipient: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b',
  limit: 100
});

Query by Token Pair

Analyze Token Trading

// Get all ETH -> USDC swaps on Base to Arbitrum
const ethUsdcSwaps = await queryOrders('https://api.aori.io', {
  inputToken: '0x4200000000000000000000000000000000000006', // WETH on Base
  outputToken: '0xaf88d065e77c8cc2239327c5edb3a432268e5831', // USDC on Arbitrum
  inputChain: 'base',
  outputChain: 'arbitrum',
  status: 'completed'
});

Query by Time Range

Historical Analysis

// Get orders from the last 24 hours
const yesterday = Math.floor(Date.now() / 1000) - (24 * 60 * 60);
const today = Math.floor(Date.now() / 1000);

const recentOrders = await queryOrders('https://api.aori.io', {
  minTime: yesterday,
  maxTime: today,
  limit: 50
});

Query by Value Range

Filter by Trade Size

// Get high-value trades (>$10,000)
const highValueTrades = await queryOrders('https://api.aori.io', {
  minValue: '10000',
  status: 'completed',
  limit: 25
});

// Get trades in a specific value range
const mediumTrades = await queryOrders('https://api.aori.io', {
  minValue: '1000',
  maxValue: '10000',
  limit: 50
});

Pagination Example

Handle Large Datasets

async function getAllUserOrders(userAddress: string) {
  const allOrders = [];
  let currentPage = 1;
  let hasMorePages = true;

  while (hasMorePages) {
    const response = await queryOrders('https://api.aori.io', {
      offerer: userAddress,
      page: currentPage,
      limit: 100
    });

    allOrders.push(...response.orders);
    
    hasMorePages = currentPage < response.pagination.totalPages;
    currentPage++;
  }

  return allOrders;
}