tables_raw_item

Endpoint

POST /v1/tables/{table_handle}/raw_item

Request Body

{
  "key": { "addr": "0x1" },
  "key_type": "vector<u8>",
  "value_type": "vector<u8>"
}

Response

Success Response (200)

Returns the raw BCS-encoded bytes as a hex string:

{
  "bytes": "0x0123456789abcdef..."
}

The bytes must be decoded using BCS deserialization based on the specified value_type.

Error Responses

Status	Error Code	Description
400	invalid_input	Invalid table handle, types, or key
404	table_item_not_found	Key doesn't exist
404	table_not_found	Table doesn't exist

Code Examples

curl -s -X POST "https://api-aptos-mainnet.n.dwellir.com/YOUR_API_KEY/v1/tables/0xabc/raw_item" \
  -H "Content-Type: application/json" \
  -d '{"key_type":"vector<u8>","value_type":"vector<u8>","key":"0x00"}'

Python example with BCS decoding:

import requests
from aptos_sdk import bcs

response = requests.post(
    "https://api-aptos-mainnet.n.dwellir.com/YOUR_API_KEY/v1/tables/{handle}/raw_item",
    json={"key_type": "address", "value_type": "u64", "key": "0x1"}
)
raw_bytes = bytes.fromhex(response.json()['bytes'][2:])  # Remove 0x prefix
value = bcs.deserialize(raw_bytes, bcs.uint64)

Use Cases

Raw table queries serve specialized use cases requiring direct BCS access:

1. Custom Deserialization: Deserialize complex or custom Move types that aren't supported by the standard JSON API, using language-specific BCS libraries.

2. Performance Optimization: For high-throughput applications, BCS deserialization can be faster than JSON parsing, especially for numeric-heavy data.

3. Type Flexibility: Query tables without knowing the exact Move type structure, then decode based on discovered schemas or partial type information.

4. Cross-Language Compatibility: BCS is the canonical serialization format for Move. Use raw bytes for interoperability between different SDK implementations.

5. Verification and Hashing: Compute cryptographic hashes or signatures over the exact on-chain bytes without JSON encoding ambiguities.

6. Low-Level Debugging: Inspect raw serialization format to debug encoding issues or verify data integrity.

Best Practices

BCS Knowledge Required: This endpoint requires deep understanding of BCS serialization and Move type layouts. Use the standard /tables/{handle}/item endpoint unless you have specific needs for raw bytes.

Type Specification: While you must specify value_type, the returned bytes are not validated against this type. It's your responsibility to ensure correct deserialization.

SDK Support: Use BCS libraries from official SDKs (aptos-sdk for Python, @aptos-labs/ts-sdk for TypeScript) rather than implementing BCS deserialization yourself.

Hex Encoding: Response bytes are 0x-prefixed hex strings. Strip the prefix before converting to byte arrays in most languages.

Performance Trade-offs: While BCS deserialization can be faster, the overhead of HTTP requests typically dominates. Only use raw queries if you're batch-processing many items.

Performance Considerations

Performance characteristics are identical to the standard table item endpoint. The difference is purely in response format - JSON vs raw bytes. Response times are typically 50-150ms.

For applications processing millions of table items, the reduced parsing overhead of BCS can save 10-30% CPU time compared to JSON deserialization, but network I/O remains the bottleneck.