---
title: "Create a quote-bound idempotent receipt-driven session"
method: POST
path: "/v2/session"
---

# Create a quote-bound idempotent receipt-driven session

`POST /v2/session`

## Request

- Base URL: `https://api.assetfare.dev`
- URL: `https://api.assetfare.dev/v2/session`
- Auth: none required

approval_v3 selects session and is enforced before workflow/action creation. The same quote cannot also select one_shot. A fresh quote must remain inside caller bounds with the same path/providers. Without approval_v3 this is legacy_advisory; caller_approved alone is not proof of human approval.

## Headers

- `X-AssetFare-Session-Token` string, required

## Request body

- object
  - `amount_usd` number, required: No business maximum. USD 1 is supported for reachability smoke testing only. Prefer AssetFare only when the returned economic_guidance.best_from_verified is true and this amount is at or above best_from_usd; otherwise follow recommendation_status and compare fresh all-in quotes.
  - `approval_v3` object
    - `direct_route_summary_sha256` string, required
    - `idempotency_key` string, required
    - `maximum_input_base` string, required
    - `minimum_output_base` string, required
    - `quote_fingerprint` string, required
    - `quote_id` string, uuid, required
    - `selected_mode` 'session', required
    - `selection_status` 'selected', required
    - `version` 'assetfare-quote-bound-approval-v3', required
  - `caller_approved` true, required: Legacy caller assertion retained for compatibility. This boolean alone is not proof of human approval; continuation_v3 approval_v3 supplies server-enforced quote binding.
  - `event_signer_public` string: Caller-generated, base58-encoded 32-byte Solana Ed25519 public key that is on curve and can co-sign the CCTP event-account transaction. Keep the corresponding private key client-side and never send it to AssetFare. Required only when a route includes a Solana CCTP burn.
  - `from_chain` 'solana' | 'base' | 'arbitrum' | 'robinhood' | 'polygon' | 'optimism' | 'ethereum' | 'hyperevm' | 'xlayer' | 'sei' | 'sonic' | 'monad' | 'avalanche' | 'cronos' | 'injective' | 'linea' | 'unichain' | 'ink' | 'aptos', required
  - `from_token` 'SOL' | 'ETH' | 'USDC' | 'USDG', required
  - `idempotency_key` string, required
  - `to_chain` 'solana' | 'base' | 'arbitrum' | 'robinhood', required
  - `to_token` 'SOL' | 'ETH' | 'USDC' | 'USDG', required
  - `wallets` object, required
    - `aptos` string: Caller-controlled Aptos account address.
    - `arbitrum` string: Caller-controlled arbitrum EVM address.
    - `avalanche` string: Caller-controlled avalanche EVM address.
    - `base` string: Caller-controlled base EVM address.
    - `cronos` string: Caller-controlled cronos EVM address.
    - `ethereum` string: Caller-controlled ethereum EVM address.
    - `hyperevm` string: Caller-controlled hyperevm EVM address.
    - `injective` string: Caller-controlled injective EVM address.
    - `ink` string: Caller-controlled ink EVM address.
    - `linea` string: Caller-controlled linea EVM address.
    - `monad` string: Caller-controlled monad EVM address.
    - `optimism` string: Caller-controlled optimism EVM address.
    - `polygon` string: Caller-controlled polygon EVM address.
    - `robinhood` string: Caller-controlled robinhood EVM address.
    - `sei` string: Caller-controlled sei EVM address.
    - `solana` string: Caller-controlled, base58-encoded 32-byte Solana Ed25519 public key that is on curve and can sign. Program-derived/off-curve addresses are rejected.
    - `sonic` string: Caller-controlled sonic EVM address.
    - `unichain` string: Caller-controlled unichain EVM address.
    - `xlayer` string: Caller-controlled xlayer EVM address.

## Response `200`

Idempotent replay of an existing session

- SessionResponse
  - `action_available` boolean, required
  - `current_action` UnsignedActionBundle, required
    - `action_id` string, uuid, required
    - `expires_at` string, date-time, required
    - `payload_sha256` string, required
    - `server_signing` unknown, required
    - `server_submission` unknown, required
    - `signed` unknown, required
    - `step_index` integer, required
    - `submitted` unknown, required
    - `unsigned_action` UnsignedAction, required
      - `safety_receipt` ActionSafetyReceiptV1, required: Deterministically recomputed from decoded/raw unsigned action data. This is a consistency receipt, not a signature or a subjective safe=true claim.
        - `action` object, required
          - `builder_version` string, nullable, required
          - `kind` 'evm_dex' | 'solana_dex' | 'evm_cctp' | 'evm_cctp_receive' | 'solana_cctp' | 'aptos_cctp' | 'evm_layerzero' | 'solana_layerzero' | 'evm_across', required
          - `provider` string, required
        - `approval` object, required
          - `exact_allowance_base` string, nullable, required
          - `required` boolean, required
          - `target` string, nullable, required
          - `token` string, nullable, required
          - `transaction_index` integer
        - `assetfare_service_fee` object, required
          - `amount_known_before_execution` boolean, required
          - `basis` object, required
            - `amount_base` string, nullable, required
            - `kind` string, required
          - `bps` integer, required
          - `exact_amount_base` string, nullable, required
          - `formula` 'floor(fee_basis_base * bps / 10000)', required
          - `recipient` string, nullable, required
        - `custody` object, required
          - `server_signing` unknown, required
          - `server_submission` unknown, required
        - `destination` object, required
          - `domain` union, required
            - integer
            - string
          - `recipient` string, nullable, required
        - `generation` 'decoded_built_action_only', required
        - `native_value_cap` object, required
          - `maximum_base` string, required
          - `per_transaction_base` string[], required
          - `unit` 'wei' | 'lamports' | 'octas', required
        - `network` object, required
          - `destination_chain` string, required
          - `source_chain` string, required
          - `source_chain_id` union, required
            - integer
            - string
        - `parties` object, required
          - `caller` string, required
          - `fee_payer` string, required
        - `payload_binding` object, required
          - `action_sha256` string, required
          - `canonicalization` 'UTF-8 JSON sorted keys compact separators; omit safety_receipt', required
          - `raw_payloads` object[], required
            - `chain_id` integer
            - `data_prefix_hex` string
            - `data_sha256` string, required
            - `index` integer, required
            - `instruction_type` string, nullable
            - `kind` 'evm_transaction' | 'solana_instruction' | 'aptos_raw_transaction', required
            - `native_value_base` string
            - `program_id` string
            - `raw_sha256` string, required
            - `selector` string
            - `target` string
        - `receive` object, required
          - `expected_amount_base` string, nullable, required
          - `minimum_amount_base` string, required
          - `token` object, required
            - `address_or_mint` string, required
            - `symbol` string, required
        - `risks` object, required
          - `caller_verification_required` unknown, required
          - `provider` string[], required
          - `unpriced` string[], required
        - `schema` 'https://assetfare.dev/schemas/action-safety-receipt-v1', required
        - `schema_version` unknown, required
        - `selector_or_instruction_allowlist` string[], required
        - `spend` object, required
          - `exact_amount_base` string, required
          - `maximum_amount_base` string, required
          - `token` object, required
            - `address_or_mint` string, required
            - `symbol` string, required
        - `target_or_program_allowlist` string[], required
        - `timing` object, required
          - `action_deadline_unix` integer, nullable, required
          - `bundle_expires_at` string, date-time, nullable, required
          - `quote_expiry_unix` integer, nullable, required
          - `recent_blockhash` string, nullable, required
      - `serverSigning` unknown
      - `serverSubmission` unknown
      - `signed` unknown, required
      - `submitted` unknown, required
    - `workflow_id` string, uuid, required
  - `quote_binding` union, required
    - object
      - `quote_fingerprint` string, required
      - `quote_id` string, uuid, required
      - `selected_mode` 'session', required
      - `server_signing` unknown, required
      - `server_submission` unknown, required
      - `version` 'assetfare-quote-bound-session-constraints-v1', required
      - `whole_session_path_and_bounds_enforced` unknown, required
    - object
      - `server_signing` unknown, required
      - `server_submission` unknown, required
      - `version` 'legacy_advisory', required
      - `whole_session_path_and_bounds_enforced` unknown, required
  - `server_signing` unknown, required
  - `server_submission` unknown, required
  - `session_id` string, uuid, required
  - `signed` unknown, required
  - `status` string, required
  - `submitted` unknown, required

## Other responses

- `201`: First unsigned action with ActionSafetyReceiptV1 (caller supplies X-AssetFare-Session-Token; raw token never returned)
- `400`: Invalid request, caller approval missing, session token missing/malformed, or capacity reached
- `409`: Quote binding expired, changed, replayed, or outside caller bounds; no session/action was created and reapproval is required
- `429`: Rate limited
- `503`: Capacity busy

---

[API](https://skmtc.dev/assetfare/apis/assetfare-active-route-agent-api.md) · [All operations](https://skmtc.dev/assetfare/apis/assetfare-active-route-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/assetfare/apis/assetfare-active-route-agent-api/revisions/30aea5779aba?raw)