Read-Only Function Calls

This endpoint allows you to make read-only calls to smart contract functions. The response is cached for future requests.

Endpoint

POST /contract-calls/read-only/{contractAddress}/{contractName}/{functionName}

Path Parameters

contractAddress: The principal address of the contract (e.g., ST252TFQ08T74ZZ6XK426TQNV4EXF1D4RMTTNCWFA)
contractName: The name of the contract (e.g., media3-action-proposals-v2)
functionName: The name of the function to call (e.g., get-proposal)

Request Body

{
  "functionArgs": [
    {
      "type": "uint",
      "value": "3"
    }
  ],
  "network": "testnet",
  "senderAddress": "ST252TFQ08T74ZZ6XK426TQNV4EXF1D4RMTTNCWFA",
  "strictJsonCompat": true,
  "preserveContainers": false,
  "cacheControl": {
    "bustCache": false,
    "skipCache": false,
    "ttl": 3600
  }
}

Request Body Parameters

functionArgs: Array of arguments to pass to the function (using simplified Clarity value format)
network (optional): The Stacks network to use (mainnet or testnet, defaults to testnet)
senderAddress (optional): The address to use as the sender (defaults to the contract address)
strictJsonCompat (optional): Whether to ensure values are JSON compatible (defaults to true)
preserveContainers (optional): Whether to preserve container types in the output (defaults to false)
cacheControl (optional): Options to control caching behavior:
- bustCache (optional): If true, bypass the cache and force a fresh request (defaults to false)
- skipCache (optional): If true, don't cache the result of this request (defaults to false)
- ttl (optional): Custom time-to-live in seconds for this specific request (overrides default TTL)

Timeout and Retry Behavior

The API implements automatic timeouts and retries for contract calls:

Default Timeout: 5 seconds for all Stacks API calls
Automatic Retries: Failed requests are automatically retried up to 3 times with exponential backoff
Retryable Errors:
- Timeouts
- 5xx errors from the Stacks API
- Rate limit exceeded errors

When all retries are exhausted, the API returns an appropriate error response with details about the failure.

Response Format

All responses follow a standardized format to make integration consistent and error handling predictable.

Success Response

{
  "success": true,
  "data": {
    // The decoded function return value
    "action": "ST252TFQ08T74ZZ6XK426TQNV4EXF1D4RMTTNCWFA.media3-action-send-message",
    "bond": "100000000000",
    // ... other fields
  }
}

The data field contains the decoded Clarity value returned by the contract function. The values are automatically converted to JavaScript/JSON-compatible types:

Clarity integers become JavaScript numbers (or strings for large numbers)
Clarity booleans become JavaScript booleans
Clarity strings become JavaScript strings
Clarity principals become JavaScript strings
Clarity tuples become JavaScript objects
Clarity lists become JavaScript arrays
Clarity optional values become the value or null
Clarity response values become the unwrapped value (the error is thrown if it's an error response)

Error Response

{
  "success": false,
  "error": {
    "id": "unique-error-id",
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {
      // Optional additional error details
    }
  }
}

The error response includes:

id: A unique identifier for the error instance (useful for tracking in logs)
code: A standardized error code (see Common Error Codes below)
message: A human-readable description of the error
details: Additional context-specific information about the error

Common Error Codes

INVALID_CONTRACT_ADDRESS - The contract address is not a valid Stacks address
INVALID_FUNCTION - The function doesn't exist in the contract ABI
INVALID_ARGUMENTS - The arguments don't match what the function expects
UPSTREAM_API_ERROR - Error from the Stacks API when calling the function
VALIDATION_ERROR - Error validating the request parameters
TIMEOUT - The request to the Stacks API timed out (default timeout: 5 seconds)
RATE_LIMIT_EXCEEDED - The rate limit for Stacks API requests has been exceeded

Example Requests

cURL

curl -X POST \
  https://cache.aibtc.dev/contract-calls/read-only/ST252TFQ08T74ZZ6XK426TQNV4EXF1D4RMTTNCWFA/media3-action-proposals-v2/get-proposal \
  -H "Content-Type: application/json" \
  -d '{"functionArgs": [{ "type": "uint", "value": "3" }]}' \
  -w "\n"

Node.js with Stacks.js

import { uintCV } from '@stacks/transactions';
// Or using the clarity namespace: import { Cl } from '@stacks/transactions';

async function getProposal(proposalId) {
  // Create function arguments using Stacks.js
  const functionArgs = [uintCV(proposalId)];
  
  const response = await fetch(
    'https://cache.aibtc.dev/contract-calls/read-only/ST252TFQ08T74ZZ6XK426TQNV4EXF1D4RMTTNCWFA/media3-action-proposals-v2/get-proposal',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ functionArgs }),
    }
  );
  
  const result = await response.json();
  
  if (result.success) {
    return result.data;
  } else {
    throw new Error(`API Error: ${result.error.code} - ${result.error.message}`);
  }
}

// Usage
getProposal(3)
  .then(proposal => console.log('Proposal:', proposal))
  .catch(error => console.error('Error:', error));

Python with Simplified Format

import requests
import json

def get_proposal(proposal_id):
    url = 'https://cache.aibtc.dev/contract-calls/read-only/ST252TFQ08T74ZZ6XK426TQNV4EXF1D4RMTTNCWFA/media3-action-proposals-v2/get-proposal'
    
    payload = {
        "functionArgs": [
            {
                "type": "uint",
                "value": str(proposal_id)
            }
        ]
    }
    
    response = requests.post(
        url,
        headers={'Content-Type': 'application/json'},
        data=json.dumps(payload)
    )
    
    response.raise_for_status()
    result = response.json()
    
    if result.get('success'):
        return result['data']
    else:
        error = result.get('error', {})
        raise Exception(f"API Error: {error.get('code')} - {error.get('message')}")

# Usage
try:
    proposal = get_proposal(3)
    print(f"Proposal data: {json.dumps(proposal, indent=2)}")
except Exception as e:
    print(f"Error: {e}")

Example Response

Success Response

{
  "success": true,
  "data": {
    "action": "ST252TFQ08T74ZZ6XK426TQNV4EXF1D4RMTTNCWFA.media3-action-send-message",
    "bond": "100000000000",
    "caller": "ST1F8Z1TDZQVP9P0D05VAW5MHKS2EYXZZ1PDE9Q8A",
    "concluded": false,
    "createdAt": "586130",
    "creator": "ST1F8Z1TDZQVP9P0D05VAW5MHKS2EYXZZ1PDE9Q8A",
    "endBlock": "27570",
    "executed": false,
    "liquidTokens": "2104509663564782",
    "metQuorum": false,
    "metThreshold": false,
    "parameters": "0x0d0000009f4578636974696e67206e6577732c2044414f206d656d6265727321204f75722070726f6a656374206973206d616b696e672066616e7461737469632070726f67726573732c20616e6420776527726520746872696c6c656420746f20736861726520746865206c61746573742075706461746573207769746820796f7520616c6c2e20537461792074756e656420666f72206d6f72652064657461696c7321",
    "passed": false,
    "startBlock": "27566",
    "votesAgainst": "650503728846681",
    "votesFor": "0"
  }
}

Error Response Example

{
  "success": false,
  "error": {
    "id": "a1b2c3",
    "code": "INVALID_FUNCTION",
    "message": "Function get-proposals not found in contract ST252TFQ08T74ZZ6XK426TQNV4EXF1D4RMTTNCWFA.media3-action-proposals-v2",
    "details": {
      "function": "get-proposals",
      "contract": "ST252TFQ08T74ZZ6XK426TQNV4EXF1D4RMTTNCWFA.media3-action-proposals-v2"
    }
  }
}

PreviousDecode Clarity Value NextContract ABI

Last updated 4 months ago