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

# Get Wallet

> Retrieve a wallet by external user ID

<RequestExample url="https://api.chipipay.com/v1/chipi-wallets/by-user" method="GET">
  ```bash cURL theme={null}
  curl -X GET "https://api.chipipay.com/v1/chipi-wallets/by-user?externalUserId=user_123" \
    -H "Authorization: Bearer sk_prod_xxxx" \
    -H "x-api-key: pk_xxxx" \
    -H "Content-Type: application/json"
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch(
    "https://api.chipipay.com/v1/chipi-wallets/by-user?externalUserId=user_123",
    {
      method: "GET",
      headers: {
        "Authorization": "Bearer sk_prod_xxxx",
        "x-api-key": "pk_xxxx",
        "Content-Type": "application/json"
      }
    }
  );

  const wallet = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.chipipay.com/v1/chipi-wallets/by-user",
      params={"externalUserId": "user_123"},
      headers={
          "Authorization": "Bearer sk_prod_xxxx",
          "x-api-key": "pk_xxxx",
      }
  )

  wallet = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Response theme={null}
  {
    "id": "wallet_abc123",
    "externalUserId": "user_123",
    "organizationId": "org_xyz",
    "apiPublicKey": "pk_xxxx",
    "publicKey": "0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7",
    "normalizedPublicKey": "0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7",
    "encryptedPrivateKey": "U2FsdGVkX1...",
    "isDeployed": true,
    "walletType": "CHIPI",
    "chain": "STARKNET",
    "createdAt": "2025-01-15T10:30:00Z",
    "updatedAt": "2025-01-15T10:30:00Z"
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "error": "wallet_not_found",
    "message": "No wallet found for this user"
  }
  ```
</ResponseExample>


## OpenAPI

````yaml GET /chipi-wallets/by-user
openapi: 3.1.0
info:
  title: Chipi Pay API
  description: >-
    REST API for creating self-custodial wallets, executing gasless
    transactions, and purchasing services on Starknet.
  version: 14.0.0
  license:
    name: MIT
servers:
  - url: https://api.chipipay.com/v1
security:
  - bearerAuth: []
    apiKeyAuth: []
tags:
  - name: Wallets
    description: Create and manage self-custodial Starknet wallets
  - name: Transactions
    description: Record and query blockchain transactions
  - name: SKUs
    description: Browse available services for purchase
  - name: SKU Purchases
    description: Purchase services using blockchain payments
  - name: Exchanges
    description: Currency conversion rates
paths:
  /chipi-wallets/by-user:
    get:
      tags:
        - Wallets
      summary: Get Wallet
      description: >-
        Retrieve a wallet by external user ID. Returns null (404) if no wallet
        exists for this user.
      operationId: getWallet
      parameters:
        - name: externalUserId
          in: query
          required: true
          description: Your application's user identifier
          schema:
            type: string
      responses:
        '200':
          description: Wallet found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Wallet not found for this user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    WalletResponse:
      type: object
      properties:
        id:
          type: string
          description: Internal wallet identifier
        externalUserId:
          type: string
          description: Your application's user identifier
        organizationId:
          type:
            - string
            - 'null'
          description: Organization that owns this wallet
        apiPublicKey:
          type: string
          description: The API key used to create this wallet
        publicKey:
          type: string
          description: The wallet's Starknet address (account contract address)
        normalizedPublicKey:
          type: string
          description: Lowercase, zero-padded version of the public key
        encryptedPrivateKey:
          type: string
          description: >-
            AES-encrypted private key (decryptable only with the user's encrypt
            key)
        isDeployed:
          type: boolean
          description: Whether the account contract has been deployed on-chain
        walletType:
          $ref: '#/components/schemas/WalletType'
        chain:
          $ref: '#/components/schemas/Chain'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - id
        - externalUserId
        - apiPublicKey
        - publicKey
        - normalizedPublicKey
        - encryptedPrivateKey
        - isDeployed
        - walletType
        - chain
        - createdAt
        - updatedAt
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error code
        message:
          type: string
          description: Human-readable error message
      required:
        - error
        - message
    WalletType:
      type: string
      enum:
        - CHIPI
        - READY
      description: >-
        Wallet account type. CHIPI uses OpenZeppelin account. READY uses Argent
        X account.
    Chain:
      type: string
      enum:
        - STARKNET
        - BASE
        - ARBITRUM
        - OPTIMISM
        - ROOTSTOCK
        - SCROLL
        - WORLDCHAIN
      description: Blockchain network identifier
  responses:
    Unauthorized:
      description: Unauthorized — invalid or missing API key / bearer token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Rate limit exceeded (100 requests/minute per API key)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Bearer token — use your secret key (sk_prod_xxx) for server-side calls,
        or the user's JWT for client-side calls
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Your Chipi public API key (pk_xxx)

````