Request conventions

Use stable identities, exact amounts and explicit recovery semantics throughout the integration.

Identity and authority#

Private reads require current authorized account access. Account selection is not authentication; API access is not monetary authority. See access and authority.

Requests and responses#

The proposed namespace is /v1. JSON bodies use UTF-8. Monetary quantities are integer strings in atomic units, with exact asset representation IDs. Retain request correlation IDs and contract versions.

Collections use bounded limits and opaque cursors. Keep account scope, filters and snapshot identity stable across pages. Page-size maxima, retention periods and production service limits remain unspecified.

RFC3339 UTC timestamps describe effective event time. A user's display timezone does not change that time.

Idempotency#

Persist the selected account, original method/path/body and idempotency key before submission. Keep clientOrderId, orderId, operationId and monetary nonce distinct.

After a timeout, reconcile the original instruction. A changed request under the same key must not be mistaken for a retry. The order replay/retention contract and authoritative order-operation lookup remain unresolved.

Error handling#

A retryable failure does not authorize a new movement. Use errors and retries to distinguish access, syntax, state and business-condition failures.

Sensitive information#

Avoid placing private transaction details, account information or personal data in public logs and support examples. Share sanitized correlation identifiers where sufficient. Follow the environment's released event-authenticity contract rather than implementing a guessed verifier.