Resource Format Standards

[Mandatory for Graduation] This document outlines the resources that should be exposed for common fund-transfer related use cases.

Design Principles

1. Position IDs are mandatory Any system involving positions (e.g., perpetuals, options, or prediction markets) should expose a consistent positionId (for example, pos_874201) rather than asset identifiers such as VIRTUAL, and this identifier should be used consistently across both active and historical endpoints.

2. Resources and their field descriptions are mandatory This description should explicitly explain the purpose, behavior, and expected output of the resource.

3. Self-Explanatory Field Names As they are consumed by Butler and other agents for decision-making and orchestration. Avoid vague or overloaded names (e.g. response, data, result).

4. Timestamp must be returned in ISO 8601 UTC format For example: 2025-01-13T11:05:44Z

5. Numeric identifiers for chain id (e.g. 8453) are opaque to users without prior context. Agent team should either:

   1. Document the list of chain id for chainIn and chainOut in field description OR

   2. Expose chain registry resource that maps chain IDs to human-readable network information.

6. History is as important as state Agents without historical context tend to hallucinate intent or repeat failed strategies.

7. Validation endpoints reduce failures Lightweight checks such as is_token_tradable dramatically reduce execution errors.

---

Use Case Quick References:

Token Swapping (Same/Cross-Chain)Perpetual TradingOptions TradingPrediction Market