API · Propose

Propose trade

Validates first. If allowed, creates a ServiceRequest for human attestation. If blocked, no request is created and the violations are returned.

POST/api/agent/v1/trades/proposescope: propose

Request body

Same payload as validate_trade, plus an optional rationale.

FieldTypeDescription

actionrequired

string

buysell

Direction of the trade.

assetSymbolrequired

string

Ticker.

assetTyperequired

string

cryptotradfi

Asset class.

amountUsdrequired

number

Notional in USD.

rationale

string

Short note shown to the user at attestation time. Aim for one sentence — the user's primary context for accepting.

Optional headers

FieldTypeDescription

Idempotency-Key

string · ≤128 chars

A second request inside 24 hours with the same key returns the existing record instead of creating a duplicate. Use a stable per-proposal value.

curl with idempotency

curl -X POST https://api.advisorscrypto.com/api/agent/v1/trades/propose \
  -H "Authorization: Bearer ac_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: agent-prop-2026-06-15-04f9c2" \
  -d '{
    "action": "sell",
    "assetSymbol": "BTC",
    "assetType": "crypto",
    "amountUsd": 8500,
    "rationale": "Rebalance crypto sleeve toward 20% target."
  }'

Response — allowed

200 OK

{
  "proposed": true,
  "serviceRequestId": 4192,
  "decision": {
    "allowed": true,
    "violations": [],
    "ipsVersion": 7
  },
  "message":
    "Proposal accepted by policy. Pending human attestation in the AC app."
}

Response — blocked

200 OK (no attestation created)

{
  "proposed": false,
  "decision": {
    "allowed": false,
    "violations": [
      {
        "rule": "crypto_max_allocation",
        "message": "Would push crypto sleeve to 36.4% — cap is 35%.",
        "limit": 0.35,
        "actual": 0.364
      }
    ],
    "ipsVersion": 7
  },
  "message":
    "Policy blocked this proposal. No human attestation request was created."
}

Response — idempotent replay

json

{
  "proposed": true,
  "idempotent": true,
  "serviceRequestId": 4192,
  "message":
    "Existing proposal returned (matched Idempotency-Key within 24h)."
}

What happens after attestation

User opens the AC app → Requests, sees your proposal with the agent badge and the rationale.
User accepts → AC executes against the relevant custodian and the ServiceRequest status flips to completed.
User rejects → status flips to rejected with an optional reason.
The agent can poll get_audit to learn the outcome — there’s no webhook surface yet.

Last updated 2026-06-15

Suggest an edit·Changelog