Submit a proposed action

Developer Preview

Submit the exact action your agent intends to execute. The request is structured; the prompt describes the action for people and records, while proposedTx is the canonical action Nava Guardian evaluates.

Request

curl --request POST "$NAVA_BASE_URL/transactions" \
  --header "content-type: application/json" \
  --header "x-api-key: $NAVA_AGENT_API_KEY" \
  --data '{
    "escrowAddress": "0x1111111111111111111111111111111111111111",
    "prompt": "Swap a placeholder amount using the configured policy.",
    "proposedTx": {
      "protocol": "uniswap",
      "chainId": 11155111,
      "to": "0x2222222222222222222222222222222222222222",
      "data": "0x",
      "value": "0x0"
    },
    "arbiter": "policy"
  }'

// [!include ../../../../examples/guardian-node/index.mjs:guardian-submit]

All addresses and action values above are placeholders. Replace them with the registered agent wallet and the exact venue-native action before use.

Field	Type	Required	Contract
`escrowAddress`	string	Yes	The agent's registered wallet for the proposed chain.
`prompt`	string	Yes	Non-empty description of what initiated the action. It is not a substitute for structured action data.
`proposedTx`	object	Yes	Canonical action object. It must include `protocol` and `chainId`; EVM actions use fields such as `to`, `data`, `value`, and optional `nonce`, while typed-data venues carry their native structured fields here.
`metadata`	object	No	Non-action context such as environment or trace identifiers. Do not put secrets here.
`contextLogs`	object	No	Additional debugging context. Keep it non-sensitive.
`executionSignature`	string	No	Agent execution signature when the selected execution flow requires one.
`arbiter`	`policy`	No	Selects Nava Guardian policy evaluation. Set it explicitly to `policy`.

Agent keys cannot submit the pre-encrypted transaction DTO; routing and any required encryption happen server-side.

Response

A successful submission returns 201 Created with the created transaction. Capture its non-empty requestHash and use it as the status resource identifier:

{
  "id": "11111111-2222-3333-4444-555555555555",
  "requestHash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "description": "Swap a placeholder amount using the configured policy.",
  "status": "PENDING"
}

The response can contain additional transaction fields. Do not infer the Guardian result from transaction status; poll the verdict and treat verdict.outcome as authoritative.

Safe submission behavior

Do not automatically retry POST /transactions. The Developer Preview DTO exposes no idempotency key, and a repeated POST can create another request.
On 400, correct the request. On 401, replace or re-authenticate the key. On 403, fix the scope, agent, or registered-wallet mismatch.
On 429 or a service/network failure, first determine whether Nava Service created the request. If that cannot be established, stop and reconcile rather than issuing a blind duplicate.
Never log the x-api-key value. Log only non-sensitive identifiers such as the returned requestHash.

Next, handle the verdict.

Model the outcome before wiring the response

type  = 'pending' | 'approved' | 'rejected'
 
function (: ) {
  return  === 'approved'
}
 
const mayExecute = ('approved')

Suggest changes to this page