Quoting Orders

The order server will deliver quotes to intent issuers. These are based on the available inventory provided by solvers. To avoid the need for solvers to respond to every individual quote request, the order server allows solvers to regularly push their inventory to the order server in the format of solver quotes. This approach significantly reduces the overhead for solvers and improves the efficiency of the quoting process.

Submitting Quotes

Solvers can submit their inventory quotes using the /quotes/submit endpoint. This endpoint requires API key authentication and accepts an array of quote objects.

Quote Structure

Each quote contains the following information:

{
  "fromChain": "84532", // Source chain network ID (Base Sepolia)
  "toChain": "11155420", // Destination chain network ID (Optimism Sepolia)
  "fromAsset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e", // Source asset address (address(0) for native tokens)
  "toAsset": "0x5fd84259d66Cd46123540766Be93DFE6D43130D7", // Destination asset address (address(0) for native tokens)
  "fromDecimals": 6, // Decimals of the source token
  "toDecimals": 6, // Decimals of the destination token
  "ranges": [
    {
      "minAmount": "1000000", // Minimum amount that can be swapped (in token units)
      "maxAmount": "1000000000", // Maximum amount that can be swapped (in token units)
      "quote": "0.99" // Quote rate for this range (as decimal string)
    }
  ],
  "expiry": 1672531200, // Quote expires at this Unix timestamp (seconds, no milliseconds)
  "exclusiveFor": "0x1234567890123456789012345678901234567890" // Optional: exclusive for specific address
}

Complete Submit Request Example

{
  "quotes": [
    {
      "fromChain": "84532",
      "toChain": "11155420",
      "fromAsset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
      "toAsset": "0x5fd84259d66Cd46123540766Be93DFE6D43130D7",
      "fromDecimals": 6,
      "toDecimals": 6,
      "ranges": [
        {
          "minAmount": "1000000",
          "maxAmount": "1000000000",
          "quote": "0.99"
        }
      ],
      "expiry": 1672531200
    }
  ]
}

Quote Management

It is important that solvers update their quotes periodically as market conditions change, with correct expiry dates. If your quotes expire, the order server will stop using them to match user requests.

By broadcasting quotes in this manner, solvers can:

Efficiently communicate their available liquidity across multiple chain and token pairs
Set their own pricing and fee structure
Define limits on transaction sizes they’re willing to process
Update their quotes as market conditions change
The order server then uses these broadcast quotes to match incoming user requests without needing to query solvers in real-time for every request, resulting in faster quote responses for users and reduced operational overhead for solvers

Requesting Quotes

Users can request quotes using the /quote/request endpoint. This endpoint does not require authentication and accepts an OIF (Order Intent Format) quote request.

Open Intent Framework (OIF) Compliance

The quote request endpoint adheres to the Open Intent Framework (OIF) specifications, which provides standardized protocols for intent-based interactions in decentralized systems. This compliance ensures:

Interoperability: The API follows established standards that enable seamless integration with other OIF-compliant systems
Consistency: Quote requests and responses follow a well-defined schema that developers can rely on
Future-proofing: Adherence to the OIF specification ensures compatibility with evolving intent protocols

The OIF specification defines machine-readable schemas, TypeScript interfaces, and OpenAPI documentation that govern how intent-based quote requests should be structured and processed. Our implementation follows these standards to provide a robust and standardized quoting experience.

Quote Request Structure

{
  "user": "0x0001000003014a3414841f63697cfa0e3b54c4d42b3d679f07f7f2485f",
  "intent": {
    "intentType": "oif-swap",
    "inputs": [
      {
        "user": "0x0001000003014a3414841f63697cfa0e3b54c4d42b3d679f07f7f2485f",
        "asset": "0x0001000003014a3414036cbd53842c5426634e7929541ec2318f3dcf7e",
        "amount": "23940002"
      }
    ],
    "outputs": [
      {
        "receiver": "0x0001000003aa36a714841f63697cfa0e3b54c4d42b3d679f07f7f2485f",
        "asset": "0x0001000003aa36a7141c7d4b196cb0c7b01d743fbc6116a902379c7238",
        "amount": null
      }
    ],
    "swapType": "exact-input",
    "preference": "price"
  },
  "supportedTypes": ["oif-escrow-v0", "oif-resource-lock-v0"]
}

Quote Response Structure

{
  "quotes": [
    {
      "order": null,
      "eta": null,
      "validUntil": null,
      "quoteId": null,
      "metadata": {
        "exclusiveFor": "0x1234567890123456789012345678901234567890",
        "inputs": [
          {
            "user": "0x0001000003014a3414841f63697cfa0e3b54c4d42b3d679f07f7f2485f",
            "asset": "0x0001000003014a3414841f63697cfa0e3b54c4d42b3d679f07f7f2485f",
            "amount": "23940002"
          }
        ],
        "outputs": [
          {
            "receiver": "0x0001000003014a3414841f63697cfa0e3b54c4d42b3d679f07f7f2485f",
            "asset": "0x0001000003014a3414841f63697cfa0e3b54c4d42b3d679f07f7f2485f",
            "amount": "23592576"
          }
        ]
      },
      "provider": null,
      "partialFill": false,
      "failureHandling": "refund-automatic"
    }
  ]
}

Chain & Asset Support

The order server uses quotes to determine supported chains and assets. This allows solvers to add support for new chains and assets simply by producing quotes for them.

Currently supported chains:

Ethereum Sepolia (Chain ID: 11155111)
Base Sepolia (Chain ID: 84532)
Optimism Sepolia (Chain ID: 11155420)

Currently supported tokens:

USDC on all supported chains

API Endpoints

Submit Quotes

Endpoint: POST /quotes/submit
Authentication: Required (API Key)
Content-Type: application/json
Rate Limit: None specified

Request Quote

Endpoint: POST /quote/request
Authentication: Not required
Content-Type: application/json
Rate Limit: None specified

Authentication

While authentication is not necessary to request quotes, it is required to submit quotes to the order server. All solvers must be authenticated with the order server to be able to push their inventory. Without authentication, the order server won’t be able to offer your quotes to users. Authentication is handled via API tokens that provide secure access to the order server’s protected API services.

Obtaining API Access

To get your API token, please reach out to the order server team.

Using Your API Token

If you have an API token, it must be included in all requests to the order server for reputation purposes:

For HTTP requests: Include the token in the request headers as x-api-key: YOUR_API_TOKEN

Example Request with Authentication

curl -X POST "https://your-api-server.com/quotes/submit" \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk_your_api_key_here" \
  -d '{
    "quotes": [
      {
        "fromChain": "84532",
        "toChain": "11155420",
        "fromAsset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
        "toAsset": "0x5fd84259d66Cd46123540766Be93DFE6D43130D7",
        "fromDecimals": 6,
        "toDecimals": 6,
        "ranges": [
          {
            "minAmount": "1000000",
            "maxAmount": "1000000000",
            "quote": "0.99"
          }
        ],
        "expiry": 1672531200
      }
    ]
  }'

Error Handling

The API returns standard HTTP status codes:

200 OK: Request successful
400 Bad Request: Invalid request data or validation errors
401 Unauthorized: Missing or invalid API key
403 Forbidden: API key expired or insufficient permissions
404 Not Found: No quotes available for the requested parameters
500 Internal Server Error: Server error

Rate Limits and Constraints

Maximum quotes per request: 200,000
Batch processing: Quotes are processed in batches.
Quote validation: All quotes must have non-zero values
Expiry validation: Must be valid Unix timestamp in seconds (10 digits)

Reputation System

The order server implements a sophisticated reputation system that tracks solver performance and influences quote selection. This system ensures that reliable solvers are prioritized while maintaining fair competition.

How Reputation Works

Reputation Accumulation:

Solvers earn reputation points when they successfully fill orders
The reputation is directly tied to the reward amount from filled orders
Each successful order execution increases the solver’s reputation by the reward amount

Reputation Normalization:

The system maintains two reputation metrics: reputation (raw points) and reputationNorm (normalized value)
reputationNorm is calculated as the square root of the current reputation: reputationNorm = √(reputation)
This normalization prevents high-reputation solvers from completely dominating the market

Daily Decay:

Reputation naturally decays over time to prevent stale reputation from having excessive influence
Daily decay rate: 1/120 (approximately 0.83% per day)
Formula: new_reputation = current_reputation - (current_reputation / 120)
This ensures that active solvers maintain their standing while inactive ones gradually lose influence

Quote Selection Algorithm

When multiple solvers have quotes for the same trade, the system uses a weighted random selection based on reputation:

Filter by Price: Only quotes within acceptable price ranges are considered
Reputation Weighting: Each solver’s selection probability is proportional to their reputationNorm value
Weighted Random Selection: A random number is generated and matched against cumulative reputation weights
Fair Distribution: Higher reputation solvers have better chances but don’t guarantee selection

Benefits of the Reputation System

Quality Assurance: Reliable solvers who consistently fill orders gain higher reputation
Fair Competition: The square root normalization prevents monopolization
Dynamic Market: Daily decay ensures the system adapts to changing solver performance
Incentive Alignment: Solvers are incentivized to provide competitive quotes and execute successfully
User Experience: Users benefit from higher-quality quotes from proven solvers

Monitoring Your Reputation

Solver reputation can be monitored through the Dashboard, which provides a way to view your reputation & manage your api keys:

This transparency allows solvers to understand their standing in the ecosystem and make informed decisions about their quoting strategies.