Stellar Events API

Query Stellar contract events via a paginated REST API. Filter by event type, contract, transaction, and topic patterns.

GET POST /events

List events with filters and pagination

Both methods accept the same fields — GET uses query parameters, POST uses a JSON body.

ParameterTypeDescription
limitintegerNumber of events to return (1–100, default 10)
afterstringReturn events newer than this cursor (event id)
beforestringReturn events older than this cursor (event id). Use the next field from a previous response to paginate.
qstring or objectFilter query — a string (GET & POST) or a JSON object (POST only). See syntax below.

Query Syntax (q parameter)

Filter events using key:value qualifiers. Space-separated qualifiers are AND'd. Use OR for alternatives. Parentheses group expressions.

KeyValueExample
typecontract or systemtype:contract
contractStellar contract strkey (C…)contract:CCW67...
ledgerLedger sequence numberledger:58000000
txTransaction hash (requires ledger)tx:abc123...
topicXDR-JSON ScVal objecttopic:{"symbol":"transfer"}
topic0…topic3XDR-JSON ScVal objecttopic0:{"symbol":"transfer"}

Examples

  • All contract events from a ledger
    try it → 
    ledger:58000000 type:contract
  • Transfer events for a contract
    try it → 
    contract:CBN3Y5KABXEF2VDO7HNNT43TXSNL3KWTJC2HQY4ENVVRSRXFJJBFNKSM topic0:{"symbol":"transfer"}
  • Events from a specific transaction
    try it → 
    ledger:58000000 tx:7758a34695323011e177c932cb899f3ea55c5af4d95c954e946ddddaafca0296
  • Transfer, mint, clawback, and burn events for XLM and USDC
    try it → 
    (contract:CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA OR contract:CCW67TSZV3SSS2HXMBQ5JFGCKJNXKZM7UQUWUZPUTHXSTZLEO7SJMI75) (topic0:{"symbol":"transfer"} OR topic0:{"symbol":"mint"} OR topic0:{"symbol":"clawback"} OR topic0:{"symbol":"burn"})
  • Events where a specific address appears in any topic position
    try it → 
    contract:CCW67TSZV3SSS2HXMBQ5JFGCKJNXKZM7UQUWUZPUTHXSTZLEO7SJMI75 topic:{"address":"GABC..."}

JSON Query Syntax (POST only)

In POST requests, q can be a structured JSON object instead of a string. The format uses and/or nodes and single-key qualifier objects. See the JSON Schema.

Node types

Every node is a JSON object with exactly one key:

NodeShapeDescription
Qualifier{"key": value}A single filter condition. Key must be one of the qualifier keys below.
And{"and": [expr, ...]}All children must match. Array length ≥ 1.
Or{"or": [expr, ...]}At least one child must match. Array length ≥ 1.

Qualifier keys

KeyJSON value typeExample
typestring ("contract", "system", "diagnostic"){"type":"contract"}
contractstring (Stellar contract strkey){"contract":"CCW67..."}
ledgerinteger{"ledger":58000000}
txstring (transaction hash; requires ledger){"tx":"abc123..."}
topicany JSON (XDR-JSON ScVal, matches any position){"topic":{"symbol":"transfer"}}
topic0…topic3any JSON (XDR-JSON ScVal, matches specific position){"topic0":{"symbol":"transfer"}}

JSON query examples

String syntaxJSON syntax
type:contract{"type":"contract"}
type:contract contract:CCW67...{"and":[{"type":"contract"},{"contract":"CCW67..."}]}
type:contract OR type:system{"or":[{"type":"contract"},{"type":"system"}]}
(type:contract OR type:system) contract:CCW67...{"and":[{"or":[{"type":"contract"},{"type":"system"}]},{"contract":"CCW67..."}]}
topic0:{"symbol":"transfer"}{"topic0":{"symbol":"transfer"}}
ledger:100 tx:abc{"and":[{"ledger":100},{"tx":"abc"}]}

A full POST request body using the JSON format:

{
  "limit": 10,
  "q": {
    "and": [
      {"or": [{"type": "contract"}, {"type": "system"}]},
      {"contract": "CCW67TSZV3SSS2HXMBQ5JFGCKJNXKZM7UQUWUZPUTHXSTZLEO7SJMI75"},
      {"topic0": {"symbol": "transfer"}}
    ]
  }
}

Query Limits
LimitValue
Max query length1,024 bytes
Max terms (key:value pairs)20
Max parenthesis nesting depth4
Max filter combinations after expansion20

Pagination

Results are always returned in descending order (newest first). Use the before and after cursors to page through events.

Browsing history — page backward through older events:

  1. Fetch the first page: GET /events?limit=10
  2. The response includes a next field with a cursor.
  3. Pass it as before to get the next page of older events: GET /events?limit=10&before=evt_...
  4. Repeat until data is empty.

Streaming new events — poll for events newer than the last seen:

  1. Save the id of the newest event you've seen (the first item in data).
  2. Poll with after: GET /events?after=evt_...
  3. Any events created since your last seen id are returned, newest first.

Response

{
  "object": "list",
  "url": "/events?...",
  "next": "/events?after=evt_...&...",
  "data": [
    {
      "object": "event",
      "id": "evt_yGrddDfumfmdgBDNdtycxRy",
      "url": "/events/evt_yGrddDfumfmdgBDNdtycxRy",
      "ledger": 58000000,
      "at": "2024-01-15T12:00:00+00:00",
      "tx": "abc123...",
      "type": "contract",
      "contract": "CABC...",
      "topics": [{"symbol": "transfer"}],
      "data": {"i128": {"hi": 0, "lo": 1000000}}
    }
  ]
}

Try it

curlclick to copy

    

    
    

      
Response

      
Click Submit to send a request.

    

  


  
  

    

      
      
    

    

      
    

    
    

      
curlclick to copy

      

    

    
    

      
Response

      
Click Submit to send a request.

    

  


  
  

    

      
      
    

    

      
    

    
    

      
curlclick to copy

      

    

    
    

      
Response

      
Click Submit to send a request.

    

  


  
  

    

      
      
    

    

      
    

    
    

      
curlclick to copy

      

    

    
    

      
Response

      
Click Submit to send a request.

    

  


  
  

    

      
      
    

    

      
    

    
    

      
curlclick to copy

      

    

    
    

      
Response

      
Click Submit to send a request.

    

  


  
  

    

      
      
    

    
Query (q)

    
    

      
Path

      
    

    
    

      
curlclick to copy

      

    

    
    

      
Response

      
Click Submit to send a request.

    

  


  
  

    

      
      
    

    

      
    

    
    

      
curlclick to copy

      

    

    
    

      
Response

      
Click Submit to send a request.

    

  


  







  
    GET
    /events/:id
    
Get a single event by ID

  
  


  
Returns a single event object. The :id is the opaque event ID from list responses (e.g. evt_yGrddDfumfmdgBDNdtycxRy).


  
Response

  
{
  "object": "event",
  "id": "evt_yGrddDfumfmdgBDNdtycxRy",
  "url": "/events/evt_yGrddDfumfmdgBDNdtycxRy",
  "ledger": 58000000,
  "at": "2024-01-15T12:00:00+00:00",
  "tx": "abc123...",
  "type": "contract",
  "contract": "CABC...",
  "topics": [{"symbol": "transfer"}],
  "data": {"i128": {"hi": 0, "lo": 1000000}}
}


  
Try it

  

    
  

  

    
curlclick to copy

    

  

  
  

    
Response

    
Click Submit to send a request.

  


  







  
    GET
    /health
    
Health check and server status

  
  


  
Response

  
{
  "status": "ok",
  "latest_ledger": 12345,
  "cached_ledgers": 7200,
  "network_passphrase": "..."
}


  
Try it

  

    
  

  

    
curlclick to copy

    

  

  
  

    
Response

    
Click Submit to send a request.