> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shuriken.trade/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Trade Suggestion



## OpenAPI

````yaml POST /api/v2/agents/suggestions
openapi: 3.0.3
info:
  description: Multi-chain DEX trading API for developers
  license:
    name: ''
  title: Shuriken API v2
  version: 2.0.0
servers:
  - url: https://api.shuriken.trade
security: []
tags:
  - description: SplitNOW cross-chain split plan + execute
    name: V2 Splits
  - description: Wallet archive lifecycle (archive / unarchive / bulk-archive)
    name: Wallets
  - description: Token discovery, metadata, and pricing
    name: V2 Tokens
  - description: Quote and execute swaps
    name: V2 Swap
  - description: Limit orders and stop-loss
    name: V2 Trigger
  - description: Managed-agent invocation
    name: V2 Agents
  - description: Portfolio positions and PnL
    name: V2 Portfolio
  - description: User account management
    name: V2 Account
  - description: WebSocket stream discovery, session bootstrap, and channel authorization
    name: V2 WebSocket
  - description: Perpetual trading on Hyperliquid
    name: V2 Perps
  - description: Agent-proposed trade suggestions
    name: V2 Suggestions
paths:
  /api/v2/agents/suggestions:
    post:
      tags:
        - V2 Suggestions
      operationId: create_trade_suggestion
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSuggestionBody'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse_TradeSuggestionView'
          description: Suggestion created
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
          description: VALIDATION | UNKNOWN_TOKEN | MISSING_REQUIRED_FIELDS
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
          description: INSUFFICIENT_SCOPE
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
          description: RATE_LIMITED
      security:
        - bearer_auth: []
components:
  schemas:
    CreateSuggestionBody:
      properties:
        amountInUsd:
          description: Optional sizing hint in USD.
          format: double
          nullable: true
          type: number
        asset:
          description: Token address. Direction is implicit from `side`.
          type: string
        confidence:
          description: 'Optional confidence: `LOW`, `MEDIUM`, or `HIGH`.'
          nullable: true
          type: string
        networkId:
          description: '`common.NetworkId` enum name (`SOL`, `BASE`, `BSC`, `MONAD`, …).'
          type: string
        rationale:
          description: Why you're suggesting this trade. ≤500 chars.
          type: string
        side:
          description: '`BUY` or `SELL`.'
          type: string
      required:
        - side
        - networkId
        - asset
        - rationale
      type: object
    ApiResponse_TradeSuggestionView:
      description: V2 success response envelope
      properties:
        data:
          description: >-
            Outbound `TradeSuggestion` JSON shape (response from create / list /

            dismiss / ack). The `state` field is derived; the timestamps remain
            the

            source of truth.
          properties:
            actedAt:
              format: date-time
              nullable: true
              type: string
            agentKey:
              $ref: '#/components/schemas/TradeSuggestionAgentKey'
            amountInUsd:
              format: double
              nullable: true
              type: number
            asset:
              $ref: '#/components/schemas/TradeSuggestionAsset'
            confidence:
              description: Serialized as the proto enum name, e.g. "MEDIUM".
              nullable: true
              type: string
            createdAt:
              format: date-time
              type: string
            dismissReason:
              nullable: true
              type: string
            dismissedAt:
              format: date-time
              nullable: true
              type: string
            expiresAt:
              format: date-time
              type: string
            id:
              type: string
            linkedTaskId:
              nullable: true
              type: string
            networkId:
              description: Serialized as the proto enum name, e.g. "SOL" / "BASE".
              type: string
            rationale:
              type: string
            side:
              description: Serialized as the proto enum name, e.g. "BUY" / "SELL".
              type: string
            state:
              $ref: '#/components/schemas/SuggestionState'
          required:
            - id
            - state
            - createdAt
            - expiresAt
            - side
            - networkId
            - asset
            - rationale
            - agentKey
          type: object
        pagination:
          $ref: '#/components/schemas/PaginationInfo'
          nullable: true
        requestId:
          type: string
      required:
        - data
        - requestId
      type: object
    ApiErrorResponse:
      description: V2 error response envelope
      properties:
        error:
          $ref: '#/components/schemas/ApiErrorDetail'
        requestId:
          type: string
      required:
        - error
        - requestId
      type: object
    TradeSuggestionAgentKey:
      description: Lightweight handle for the agent key that posted the suggestion.
      properties:
        id:
          type: string
        name:
          type: string
      required:
        - id
        - name
      type: object
    TradeSuggestionAsset:
      description: |-
        Asset metadata enriched onto the response — consumers don't have to call
        `get_token_info` separately. The bare address is on the underlying row.
      properties:
        address:
          type: string
        name:
          type: string
        priceUsd:
          format: double
          nullable: true
          type: number
        symbol:
          type: string
      required:
        - address
        - symbol
        - name
      type: object
    SuggestionState:
      description: >-
        Derived suggestion lifecycle. Computed in the service layer from the
        three

        nullable timestamps + wall clock; never persisted as a column.
      enum:
        - OPEN
        - ACTED
        - DISMISSED
        - EXPIRED
      type: string
    PaginationInfo:
      description: Page-based pagination info (per RFC)
      properties:
        hasMore:
          type: boolean
        limit:
          format: int32
          minimum: 0
          type: integer
        page:
          format: int32
          minimum: 0
          type: integer
        total:
          format: int32
          minimum: 0
          nullable: true
          type: integer
      required:
        - page
        - limit
        - hasMore
      type: object
    ApiErrorDetail:
      description: V2 error detail
      properties:
        code:
          type: string
        details: {}
        message:
          type: string
      required:
        - code
        - message
      type: object
  securitySchemes:
    bearer_auth:
      bearerFormat: JWT or sk_{keyId}_{secret}
      description: >-
        Use `Authorization: Bearer <jwt>` for user auth or `Authorization:
        Bearer sk_{keyId}_{secret}` for API key auth.
      scheme: bearer
      type: http

````