Your first governed trading order
Four steps from an empty account to a perp order that passes through your own trading policies — with curl or any MCP client. Nothing here bypasses governance.
Create an agent and copy its riv_ key
In the app, create the agent that will trade. The riv_ key is shown once — put it in the Authorization header, or in RIV_API_KEY for MCP.
Open Agents →Connect the venue
Connect the agent to Hyperliquid (testnet first). Riv checks the approved agent wallet and the builder-fee approval before the connection goes active.
Open Connections →Create the first trading policy
Set the limits Riv enforces on every order — leverage, position size, assets, daily loss. With no policy in effect, every order is blocked (fail-closed).
Open Trading policies →Send the first governed order
Pick curl or MCP. The example is small on purpose: BTC, market, 12 USDC notional, 2x leverage.
curl -X POST https://riventa.dev/api/v1/trading/authorize \
-H "Authorization: Bearer riv_..." \
-H "Idempotency-Key: $(uuidgen)" \
-H "content-type: application/json" \
-d '{"asset":"BTC","side":"buy","orderType":"market","notional":12,"leverage":2}'Idempotency-Key is mandatory: reuse the same value to retry the same order; a new order needs a new value.
What comes back
Two independent levels: status is the governance decision, execution.status is what the venue did. approved means your policies allowed the order — only execution tells whether it filled.
200 · approved and filled
202 · waiting for human approval
422 · allowed by policy, refused by the venue
- A blocked order is a normal 200 with status "blocked" and a reasonCode — the policy worked. Adjust the order and resubmit with a new Idempotency-Key.
- Through MCP, place_order returns the same information as text: the decision, the reason, the execution outcome and the ledger activityId.