Intent Schema

This page describes the current public request shape for:

• POST /api/intents/submit

and the field mapping back to the CrossChainIntent typed data used by the EVM contract path.

Public submit body

Required fields:

Field	Type	Notes
intentId	0x + 64 hex chars	Client-side identifier used throughout the app flow. The contract-emitted canonical intent ID can still replace it after submit.
sender	string	EVM source routes use 20-byte hex; Midnight source routes use 32-byte canonical hex.
fromChain	positive integer	Source chain ID.
toChain	positive integer	Destination chain ID.
fromToken	string	Address or token ID encoded in the address field shape for the source chain family.
toToken	string	Address or token ID encoded in the address field shape for the destination chain family.
amount	decimal string	Big integer amount.
minAmountOut	decimal string	Big integer minimum receive amount.
recipient	string	Receiver address in the destination chain family format.
nonce	decimal string	Per-chain replay-protection nonce.
deadline	positive integer	Unix timestamp in seconds.
signature	hex string	Shape depends on route family.

Optional behavior:

• shielded may be sent in the request body even though it is not part of the core IntentSchema object. Treat it as an optional route flag, not a universal baseline field.

Field mapping to the EVM typed-data struct

The EVM contract path signs this struct:

Backend JSON field	EIP-712 struct field
sender	user
fromChain	sourceChain
toChain	destinationChain
fromToken	sourceToken
toToken	destinationToken
amount	amount
minAmountOut	minReceived
deadline	deadline
nonce	nonce

intentId is not part of the EVM typed-data struct itself. It is carried through the app and backend flow, and the backend can replace it with the canonical contract-emitted value after submission.

Address rules by chain family

The intent validator enforces different widths by chain family:

• EVM: 0x + 40 hex chars
• Midnight: 0x + 64 hex chars

That rule applies to:

• sender
• fromToken
• recipient
• toToken

The safest public advice is: always normalize Midnight addresses to canonical hex before submit.

Signature rules by route

Signature behavior is route-specific:

• EVM-source routes require a normal 65-byte EVM signature.
• Cross-family source routes accept hex bytes; clients use "0x" as the placeholder signature.
• EVM-source intents targeting a non-EVM destination use an EVM-shaped placeholder signature because the destination leg goes through an off-chain coordinator path.

That means builders should not generalize the EVM signature rule across every experimental route family.

Example: stable EVM-source request

{
  "intentId": "0x3e0db42d46f79ec4a5282cb2b8e1eb1b3d22d2b1b54d04a10f0f2a58f75f6b26",
  "sender": "0x1111111111111111111111111111111111111111",
  "fromChain": 421614,
  "toChain": 84532,
  "fromToken": "0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d",
  "toToken": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
  "amount": "1000000",
  "minAmountOut": "990000",
  "recipient": "0x2222222222222222222222222222222222222222",
  "nonce": "0",
  "deadline": 1767225600,
  "signature": "0x..."
}

Notes for builders

• fetch nonce from POST /api/intents/get-nonce
• fetch the domain from POST /api/intents/get-domain
• treat the backend response after submit as authoritative for the final intent ID
• do not assume the same signing path applies to cross-family routes

Related docs:

• Quickstart
• Wallet App Integration
• Supported Chains Overview