Call RegisterStreamConsumer with the stream ARN and a unique consumer name; the response includes a ConsumerARN — wait until DescribeStreamConsumer shows ConsumerStatus=ACTIVE before subscribing
For each shard, call SubscribeToShard with the ConsumerARN and shard ID; provide a StartingPosition specifying AT_LATEST, AT_TIMESTAMP, AT_SEQUENCE_NUMBER, or AFTER_SEQUENCE_NUMBER
Process the streaming HTTP/2 response: each SubscribeToShard call returns a 5-minute streaming session delivering records via server-sent events at up to 2 MB/s per shard dedicated throughput
Renew subscriptions before the 5-minute session expires by issuing a new SubscribeToShard call on the same shard; use the ContinuationSequenceNumber from the last received record as the new starting position
Handle shard splits and merges: when a shard is split, SubscribeToShard on the parent returns an event indicating it is closed; call ListShards to discover the two child shards and subscribe to each
Monitor consumer-level metrics: GetShardIterator is not used for enhanced fan-out — RegisterStreamConsumer has a limit of 5 calls per second per account; consumer limit is 20 per stream by default, or 50 for accounts with On-demand Advantage
Known gotchas
Enhanced fan-out subscriptions are per-shard and per-registered-consumer; registering 5 consumers on a 10-shard stream creates 50 potential subscription slots — each subscription is billed independently from standard GetRecords reads
A SubscribeToShard call is rejected with ResourceInUseException if another active subscription already exists for the same consumer+shard combination; implement a lock or coordination mechanism before subscribing
The 5-minute session timeout is a hard limit from the service; your consumer must handle session expiry gracefully by catching the SessionExpiredException and re-subscribing using the last received ContinuationSequenceNumber
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp