POST
/
v1
/
messages
curl --request POST \
  --url https://api.pond3r.xyz/v1/messages \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "prompt": "Get the current price of ETH"
}'
{
  "processingId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "PENDING"
}

​
Overview

The messages endpoint allows you to submit natural language queries about blockchain data. The API now processes messages asynchronously, providing a more robust way to handle longer-running queries.

​
Request Flow

  1. Submit your query using the /v1/messages endpoint
  2. Receive a processingId to track your request
  3. Poll the /v1/messages/{processingId}/status endpoint to get the final result

​
Examples

​
Submitting a Query

const axios = require('axios');

async function submitQuery() {
  try {
    const response = await axios.post('https://api.pond3r.xyz/v1/messages', {
      prompt: 'Get the current price of ETH'
    }, {
      headers: {
        'x-api-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
      }
    });
    
    return response.data.processingId;
  } catch (error) {
    console.error('Error submitting query:', error.response ? error.response.data : error.message);
    throw error;
  }
}

​
Checking Status and Getting Results

const axios = require('axios');

async function getResult(processingId) {
  try {
    const response = await axios.get(`https://api.pond3r.xyz/v1/messages/${processingId}/status`, {
      headers: {
        'x-api-key': 'YOUR_API_KEY'
      }
    });
    
    return response.data;
  } catch (error) {
    console.error('Error checking status:', error.response ? error.response.data : error.message);
    throw error;
  }
}

// Example of waiting for the result
async function waitForResult(processingId, maxAttempts = 30, interval = 2000) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    const status = await getResult(processingId);
    
    if (status.status === 'FINISHED') {
      return status.result;
    } else if (status.status === 'ERROR') {
      throw new Error(status.errorMessage || 'Processing failed');
    }
    
    // Wait before next attempt
    await new Promise(resolve => setTimeout(resolve, interval));
  }
  
  throw new Error('Timeout waiting for result');
}

// Usage example
async function main() {
  try {
    const processingId = await submitQuery();
    console.log('Processing ID:', processingId);
    
    const result = await waitForResult(processingId);
    console.log('Final result:', result);
  } catch (error) {
    console.error('Error:', error.message);
  }
}

​
Response Statuses

The status endpoint can return the following statuses:

  • PENDING: The message has been received and is waiting to be processed
  • PROCESSING: The message is currently being processed
  • FINISHED: Processing is complete and the result is available
  • ERROR: An error occurred during processing

​
Error Handling

When an error occurs, the status response will include an errorMessage field with details about what went wrong. Common error scenarios include:

  • Invalid API key
  • Malformed query
  • Processing timeout
  • Internal server errors

​
Best Practices

  1. Always implement proper error handling and retry logic
  2. Use appropriate polling intervals (2-3 seconds recommended)
  3. Set reasonable timeouts for your application
  4. Store the processingId for later reference if needed
  5. Consider implementing a webhook system for production applications

Authorizations

​
x-api-key
string
header
required

Body

application/json

Response

201
application/json

Message submitted for processing

The response is of type object.