Skip to main content
HomeDocsDashboard
BUY DTAO
How RESI WorksDocumentationStatus Page
XLinkedInDiscord

RESI API Reference

Access decentralized property valuations programmatically.

Under Development

The RESI API is currently under development. Documentation reflects planned functionality.

API overview​

The RESI API provides access to property price predictions from winning models, historical validation datasets, model performance metrics, and execution provenance.

REST API​

Standard HTTP endpoints for property valuations and data access.

Base URL​

https://api.resi.ai/v1

Get property valuation​

Request a price prediction for a specific property.

POST /inference

Request body:

{
  "property_data_hash": "ipfs://Qm...",
  "request_date": "2024-11-21"
}

Response:

{
  "predicted_price": 450000,
  "prediction_date": "2024-11-21T14:30:00Z",
  "model_id": "model_abc123",
  "model_accuracy": {
    "r_squared": 0.89,
    "last_14_days": [
      {"date": "2024-11-20", "r_squared": 0.88},
      {"date": "2024-11-19", "r_squared": 0.90}
    ]
  },
  "execution_proof": "0x..."
}

Batch property valuation​

Request valuations for multiple properties.

POST /inference/batch

Request body:

{
  "properties": [
    {
      "property_data_hash": "ipfs://Qm...",
      "request_date": "2024-11-21"
    },
    {
      "property_data_hash": "ipfs://Qm...",
      "request_date": "2024-11-21"
    }
  ]
}

Response: Array of individual valuation responses.

Get validation datasets​

Retrieve validation datasets used for model benchmarking.

Latest dataset:

GET /validation-set/latest

Historical dataset:

GET /validation-set/historic?date=2024-11-15

Response:

{
  "date": "2024-11-21",
  "property_count": 1247,
  "data_url": "https://data.resi.ai/validation/2024-11-21.json",
  "hash": "0x..."
}

Property data format​

Properties are referenced by IPFS hash pointing to standardized JSON.

Standard property fields:

{
  "address": {
    "street": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94102",
    "latitude": 37.7749,
    "longitude": -122.4194
  },
  "characteristics": {
    "square_feet": 2000,
    "bedrooms": 3,
    "bathrooms": 2,
    "lot_size": 5000,
    "year_built": 1950,
    "property_type": "single_family",
    "stories": 2
  },
  "features": {
    "garage": true,
    "pool": false,
    "updated_kitchen": true
  }
}

Required fields: Address, square footage, bedrooms, bathrooms.

Optional fields: Models handle missing data appropriately.

Error handling​

Standard HTTP status codes: 200 (success), 400 (invalid request), 404 (not found), 429 (rate limit exceeded), 500 (server error).

Error response:

{
  "error": "Invalid property data format",
  "code": "INVALID_FORMAT",
  "details": "Missing required field: square_feet"
}

WebSocket API​

Real-time streaming of validation results and model updates.

Connection​

wss://api.resi.ai/v1/stream

Validation results stream​

Subscribe to real-time validation results as they complete.

Subscribe message:

{
  "action": "subscribe",
  "stream": "validation_results"
}

Stream messages:

{
  "event": "validation_complete",
  "date": "2024-11-21",
  "results": [
    {
      "model_id": "model_abc123",
      "r_squared": 0.89,
      "rank": 1
    }
  ]
}

Model updates stream​

Subscribe to new model submissions and status changes.

Subscribe message:

{
  "action": "subscribe",
  "stream": "model_updates"
}

Stream messages:

{
  "event": "model_submitted",
  "model_id": "model_new456",
  "submission_time": "2024-11-21T10:00:00Z",
  "miner_uid": 42
}

Price updates stream​

Subscribe to winning model changes that affect API pricing.

Subscribe message:

{
  "action": "subscribe",
  "stream": "price_updates"
}

Stream messages:

{
  "event": "model_changed",
  "previous_model": "model_abc123",
  "new_model": "model_xyz789",
  "effective_time": "2024-11-21T14:00:00Z"
}

Oracle integration​

Bring RESI property valuations on-chain through oracle networks.

Integration pattern​

Step 1: Smart contract requests valuation with property data hash and request date.

Step 2: Oracle calls RESI REST API with property data hash.

Step 3: RESI returns prediction with predicted price, model ID, accuracy history, and execution proof.

Step 4: Oracle delivers data on-chain with signature verification.

Supported oracle networks​

Oracle networks can integrate RESI including Chainlink, Redstone, API3, and other compatible networks.

Data format on-chain​

Valuation struct example:

struct PropertyValuation {
    uint256 predictedPrice;
    uint256 predictionTimestamp;
    bytes32 modelId;
    uint16 modelAccuracy;
    bytes32 executionProof;
}

Example: RWA lending​

function requestLoan(bytes32 propertyHash) external {
    bytes32 requestId = oracle.requestPropertyValuation(
        propertyHash,
        block.timestamp
    );
    pendingRequests[requestId] = msg.sender;
}

function fulfillLoan(
    bytes32 requestId,
    PropertyValuation memory valuation
) internal {
    require(valuation.modelAccuracy > 8500, "Accuracy too low");
    uint256 loanAmount = valuation.predictedPrice * 70 / 100;
}

Security considerations​

Model provenance: Verify model ID matches expected winning model.

Accuracy history: Check historical performance before trusting valuation.

Execution proof: Verify cryptographic proof when available.

Data standardization: Ensure property data follows RESI format exactly.

SDKs and tools​

Python SDK​

pip install resi-sdk

Example usage:

from resi import ResiClient

client = ResiClient(api_key="your_key")

valuation = client.predict_price(
    property_data_hash="ipfs://Qm...",
    request_date="2024-11-21"
)

print(f"Predicted price: ${valuation.predicted_price}")
print(f"Model accuracy: {valuation.model_accuracy.r_squared}")

JavaScript SDK​

npm install @resi/sdk

Example usage:

import { ResiClient } from '@resi/sdk';

const client = new ResiClient({ apiKey: 'your_key' });

const valuation = await client.predictPrice({
  propertyDataHash: 'ipfs://Qm...',
  requestDate: '2024-11-21'
});

console.log(`Predicted price: $${valuation.predictedPrice}`);

WebSocket streaming​

const stream = client.stream('validation_results');

stream.on('validation_complete', (data) => {
  console.log('New validation results:', data);
});

Helper tools​

Data formatter: Convert property data from various sources (Zillow, Redfin, manual input) to RESI standard format.

resi-format --source zillow --input properties.csv --output formatted.json

IPFS uploader: Upload formatted property data to IPFS for on-chain references.

resi-upload --input formatted.json --output hashes.txt

Batch processor: Process multiple property valuations efficiently.

from resi import BatchProcessor

processor = BatchProcessor(api_key="your_key")
results = processor.process_file("properties.json")

Solidity contracts​

Example smart contracts for oracle integration available at:

git clone https://github.com/resi-labs-ai/resi-contracts

Testing tools​

Sandbox environment: Test API integration without rate limits.

https://sandbox.api.resi.ai/v1

Mock data generator: Generate sample property data for testing.

resi-mock-data --count 100 --output test-properties.json

Authentication and rate limits​

Authentication details and rate limit policies will be established as API launches.

Support​