Skip to Content
DocsDecode API

Decode API

Decode raw Soroban event topics and values into semantic JSON using schemas from the SEP-0048 registry.

Authentication: API key required (Authorization: Bearer nl_api_...). See API Credentials.

Decode one event

POST /v1/decode

Request body

FieldTypeRequiredDescription
networkstringyestestnet, mainnet, or futurenet
contractIdstringyesEmitting contract ID
eventNamestringnoHint when multiple schemas exist on the contract
schemaVersionnumbernoPin a specific schema version
topicsXdrstring[]one of topicsBase64 XDR topic array from RPC
topicsJsonarrayone of topicsRPC-style topic JSON (preferred when available)
valueXdrstringone of valueBase64 XDR event value
valueJsonobjectone of valueRPC-style value JSON

Provide either topicsXdr or topicsJson, and either valueXdr or valueJson.

Example

curl -X POST "http://localhost:8080/v1/decode" \
  -H "Authorization: Bearer $NARALABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "network": "testnet",
    "contractId": "CBGROPHYFCL5FNTNJF6HXVJEWPLOMHZJ3MNISPTB2JHXLGKQMO2MCWK4",
    "topicsJson": [
      {"symbol": "cntr"},
      {"symbol": "incr"}
    ],
    "valueJson": {"u32": 42}
  }'

Response

{
  "decodeStatus": "decoded",
  "eventName": "counter_incremented",
  "schemaVersion": 1,
  "fields": {
    "count": 42
  },
  "summary": "counter_incremented: count=42",
  "level2": {
    "topics": [
      {"symbol": "cntr"},
      {"symbol": "incr"}
    ],
    "value": {"u32": 42}
  }
}

When no matching schema exists, Atlas returns decodeStatus: "raw" with level-2 tagged JSON in level2 and no fields.

Batch decode

POST /v1/decode/batch
{
  "events": [
    {
      "network": "testnet",
      "contractId": "CBGROPHYFCL5FNTNJF6HXVJEWPLOMHZJ3MNISPTB2JHXLGKQMO2MCWK4",
      "topicsJson": [{"symbol": "cntr"}, {"symbol": "incr"}],
      "valueJson": {"u32": 42}
    }
  ]
}

Maximum 50 events per request.

Response

{
  "items": [ { "decodeStatus": "decoded", "...": "..." } ],
  "total": 1
}

Supported schema param types

MVP semantic decode supports: u32, i32, u64, i64, i128, u128, address, string, symbol, bool.

Param locations: data, topic_list.

Last updated on
API credentials