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
ortestnet
, defaults totestnet
)senderAddress
(optional): The address to use as the sender (defaults to the contract address)strictJsonCompat
(optional): Whether to ensure values are JSON compatible (defaults totrue
)preserveContainers
(optional): Whether to preserve container types in the output (defaults tofalse
)cacheControl
(optional): Options to control caching behavior:bustCache
(optional): If true, bypass the cache and force a fresh request (defaults tofalse
)skipCache
(optional): If true, don't cache the result of this request (defaults tofalse
)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 errordetails
: Additional context-specific information about the error
Common Error Codes
INVALID_CONTRACT_ADDRESS
- The contract address is not a valid Stacks addressINVALID_FUNCTION
- The function doesn't exist in the contract ABIINVALID_ARGUMENTS
- The arguments don't match what the function expectsUPSTREAM_API_ERROR
- Error from the Stacks API when calling the functionVALIDATION_ERROR
- Error validating the request parametersTIMEOUT
- 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"
}
}
}
Last updated