Overview
All financial action endpoints in Aegis require an Idempotency-Key header. This ensures that if a network failure causes your agent to retry a request, the action is only executed once.
How It Works
- Your agent generates a unique UUID v4 before making a financial request
- The UUID is sent in the
Idempotency-Key header
- Aegis hashes the key and checks if it has been seen before
- First time: The action is executed and the result is cached
- Subsequent requests with the same key: The cached result is returned without re-executing
Which Endpoints Require Idempotency?
Usage
Key Rules
- The key must be a valid UUID v4
- Each new action must use a unique key
- Reusing a key from a successful action returns the cached result
- Reusing a key from a failed action returns the cached error
- Keys are scoped per agent, different agents can use the same UUID without conflict
Never reuse an idempotency key for a different action. If you used key abc
for a transfer to address A, and then reuse abc for a transfer to address B,
you will get the cached result of the first transfer, the second transfer will
NOT execute.
In most languages, you can generate a UUID v4 with a single function call:
- JavaScript:
crypto.randomUUID()
- Python:
import uuid; str(uuid.uuid4())
- Go:
uuid.New().String()
- Bash:
uuidgen
