Skip to main content

​
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

  1. Your agent generates a unique UUID v4 before making a financial request
  2. The UUID is sent in the Idempotency-Key header
  3. Aegis hashes the key and checks if it has been seen before
  4. First time: The action is executed and the result is cached
  5. 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