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

# Wallet Link

> Link an external wallet after proving ownership.

Submit the signed challenge message to link the wallet to your account.
The signature must be valid for the challenge nonce that was requested.

Rate limited: 3 linking attempts per day per IP (via slowapi; linking
additionally requires a valid signed nonce, which self-throttles per account).



## OpenAPI

````yaml /openapi.json post /api/sdk/wallet/link
openapi: 3.1.0
info:
  title: Simmer API
  description: Agent-native trading infrastructure for prediction markets.
  version: 1.0.0
servers:
  - url: https://api.simmer.markets
security: []
paths:
  /api/sdk/wallet/link:
    post:
      tags:
        - sdk-wallet
      summary: Wallet Link
      description: >-
        Link an external wallet after proving ownership.


        Submit the signed challenge message to link the wallet to your account.

        The signature must be valid for the challenge nonce that was requested.


        Rate limited: 3 linking attempts per day per IP (via slowapi; linking

        additionally requires a valid signed nonce, which self-throttles per
        account).
      operationId: api_wallet_link_api_sdk_wallet_link_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WalletLinkRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletLinkResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    WalletLinkRequest:
      properties:
        address:
          type: string
          title: Address
          description: Wallet address being linked
        signature:
          type: string
          title: Signature
          description: Signature of the challenge message
        nonce:
          type: string
          title: Nonce
          description: Challenge nonce from GET /wallet/link/challenge
        signature_type:
          type: integer
          title: Signature Type
          description: 0=EOA, 1=Polymarket proxy, 2=Gnosis Safe
          default: 0
        confirm_replace_managed:
          type: boolean
          title: Confirm Replace Managed
          description: >-
            Required (true) when this link would replace an existing managed
            wallet with a different external wallet. Default false so SDK
            auto-relink paths (`_ensure_wallet_linked`) cannot silently
            overwrite a managed account when a stale `WALLET_PRIVATE_KEY` is
            left in the bot env. Explicit user calls to `client.link_wallet()`
            from simmer-sdk >= 0.16 pass this true. SIM-1574.
          default: false
        confirm_orphan_deposit_wallet:
          type: boolean
          title: Confirm Orphan Deposit Wallet
          description: >-
            Required (true) when the user has an active Polymarket deposit
            wallet (`wallet_uses_deposit_wallet=true`) and the linking address
            differs from the current `wallet_address`. The DW is owned on-chain
            by the CURRENT EOA via CREATE2; relinking to a new address would
            orphan the DW (the new key can't sign WALLET batches against it —
            funds and positions get stuck). Default false so silent orphaning is
            impossible. SIM-1611. Surfaced after the 2026-05-07 audit found 3
            already-orphaned DWs from prior relinks (da2185e0, ydir.tomas@,
            raynojam@). See `_dev/active/_polymarket-dw-phase-2/`.
          default: false
      type: object
      required:
        - address
        - signature
        - nonce
      title: WalletLinkRequest
      description: Request to link an external wallet after signing challenge.
    WalletLinkResponse:
      properties:
        success:
          type: boolean
          title: Success
        wallet_address:
          anyOf:
            - type: string
            - type: 'null'
          title: Wallet Address
        wallet_ownership:
          anyOf:
            - type: string
            - type: 'null'
          title: Wallet Ownership
        message:
          anyOf:
            - type: string
            - type: 'null'
          title: Message
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
      type: object
      required:
        - success
      title: WalletLinkResponse
      description: Response from wallet linking attempt.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError

````