---
updatedAt: 2026-06-20T07:34:07.000Z
agentTools:
  projectIndex: https://docs.wirexapp.com/llms.txt
---

# Client-side create user

Creates a new user in the Wirex system using client side Privy SDK authorization.

# OpenAPI definition

````json
{
  "components": {
    "schemas": {
      "request.UserCreateUserRetailRequest": {
        "properties": {
          "country": {
            "description": "The residence country of the user. This should be an Alpha-2 code. (e.g., US, GB, DE).\nWhen omitted, it defaults to the country Cloudflare resolves from the client IP.",
            "example": "FR",
            "type": "string"
          }
        },
        "type": "object"
      },
      "response.ErrorCategory": {
        "properties": {
          "category": {
            "type": "string"
          },
          "grpc_status_code": {
            "type": "integer"
          },
          "http_status_code": {
            "type": "integer"
          }
        },
        "type": "object"
      },
      "response.ErrorDetails": {
        "properties": {
          "details": {
            "type": "string"
          },
          "key": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "response.ErrorResponse": {
        "properties": {
          "error_category": {
            "$ref": "#/components/schemas/response.ErrorCategory"
          },
          "error_description": {
            "type": "string"
          },
          "error_details": {
            "items": {
              "$ref": "#/components/schemas/response.ErrorDetails"
            },
            "type": "array"
          },
          "error_reason": {
            "example": "ErrorInvalidField",
            "type": "string"
          }
        },
        "type": "object"
      },
      "response.IdResponse": {
        "properties": {
          "id": {
            "description": "Identifier of the created entity",
            "example": "123e4567-e89b-12d3-a456-426655440000",
            "type": "string"
          }
        },
        "required": [
          "id"
        ],
        "type": "object"
      }
    },
    "securitySchemes": {
      "ChainId": {
        "description": "EIP-155 id of the chain that the request should be executed for (e.g. 1001996)",
        "in": "header",
        "name": "X-Chain-Id",
        "type": "apiKey"
      },
      "PrivyAccessToken": {
        "description": "Access token issued by Privy authorization system. [Authentication](doc:authentication) Privy-Based Authentication section",
        "in": "header",
        "name": "Authorization",
        "type": "apiKey"
      },
      "PrivyIdentityToken": {
        "description": "Privy Identity token issued by Privy authorization system. [Authentication](doc:authentication) Privy-Based Authentication section",
        "in": "header",
        "name": "Identity",
        "type": "apiKey"
      }
    }
  },
  "info": {
    "contact": {
      "email": "company@wirexpaychain.com",
      "name": "API Support Team"
    },
    "description": "The **Wirex BaaS API** enables partners to deliver non-custodial financial services directly to their retail users. Through a single integration, partners can onboard users, verify identities, issue smart wallet–linked cards, and enable crypto-backed bank transfers—without ever handling fiat or taking custody of user funds.</br>All transactions are powered by **user-owned smart wallets**, ensuring security, transparency, and full user control. Wirex acts as the infrastructure provider, so you can focus on building exceptional user experiences while we handle the heavy lifting.",
    "title": "Wirex Retail BaaS API",
    "version": "1.0"
  },
  "openapi": "3.0.3",
  "paths": {
    "/api/v1/user/retail": {
      "post": {
        "description": "Creates a new user in the Wirex system using client side Privy SDK authorization.",
        "requestBody": {
          "content": {
            "*/*": {
              "schema": {
                "$ref": "#/components/schemas/request.UserCreateUserRetailRequest"
              }
            }
          },
          "description": "Body data",
          "x-originalParamName": "bodyData"
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/response.IdResponse"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/response.ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/response.ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/response.ErrorResponse"
                }
              }
            },
            "description": "Service Unavailable"
          }
        },
        "security": [
          {
            "ChainId": [],
            "PrivyAccessToken": [],
            "PrivyIdentityToken": []
          }
        ],
        "summary": "Client-side create user",
        "tags": [
          "Onboarding/OffChain"
        ]
      }
    }
  },
  "servers": [
    {
      "url": "https://api-baas.wirexapp.com"
    },
    {
      "url": "https://api-baas.wirexapp.tech"
    }
  ],
  "tags": [
    {
      "description": "Off-chain onboarding handles the **user's presence in the Wirex backend**, allowing the system to manage non-sensitive metadata, orchestrate KYC flows, and enable services such as card issuance and transaction monitoring.\n\n- Partners can choose between **server-side onboarding using Wirex Partner Credentials** or **frontend integration via Privy SDK**.\n- This flow includes registering the user in the off-chain system and obtaining authorization tokens for subsequent operations.\n\n---\n\n## Server-Side Onboarding\n\n### Description\nThis method is ideal for partners with their own backend infrastructure and existing user authentication systems. Partners collect and manage all required user information (e.g., email, wallet address, personal details) and use their **Wirex Partner Token** (obtained via Wirex Partner Credentials) to perform onboarding actions via API.\n\n### Key Requirements\n  - Partner must have a secure authentication system in place to authorize each individual user.\n  - Partner is responsible for collecting user details and ensuring data compliance.\n\n### Typical Flow\n  1. Authenticate via Wirex Partner Credentials to obtain a server token (see [Authorization > Wirex Partner Credentials](#tag/Authorization/Wirex-Partner-Credentials)).\n  2. Register the user by making server-side API call to [Create user](#tag/User/paths/~1api~1v1~1user/post) with necessary data.\n```bash\n     curl --request POST \\\n     --url https://api-business.wirexpaychain.tech/api/v1/user \\\n     --header 'Authorization: Bearer {your_wirex_partner_token}' \\\n     --header 'Content-Type: application/json' \\\n     --data '{\n     \"email\": \"a.grey@wirexpaychain.com\",\n     \"country\": \"FR\",\n     \"wallet_address\": \"0x7E5F4552091A69125d5DfCb7b8C2659029395Bdf\"\n     }'\n ```\n  3. Continue the onboarding flow (e.g., KYC, card issuance) using either [Wirex Partner Credentials authorization](#tag/Authorization/Wirex-Partner-Credentials) or [Wirex User Token authorization](#tag/Authorization/Wirex-User-Token).\n\n### Best For\nPlatforms that already manage their own user databases and require full backend control.\n\n---\n\n## Privy SDK\n\n### Description\nThis method allows partners to offload identity and session management by integrating **Privy SDK** directly into their client application. Wirex provides a dedicated **AppId** that enables Privy to handle login, identity verification, and session persistence on behalf of the partner.\n\n### Key Benefits\n  - No need to implement or maintain a custom login flow.\n  - Privy handles user authentication and provides tokens required for authorized API calls.\n  - Reduced compliance and data handling overhead for the partner.\n\n### Typical Flow\n  1. Integrate the Privy SDK using the `AppId` provided by Wirex. For details on integrating SDK please follow [Privy SDK docs](https://docs.privy.io/basics/react/installation)\n  2. Onboard the user via Privy to obtain access and identity tokens. **Please note that as a result of onboarding the registered user must have a linked email account and either a linked or an embedded wallet.**\n  3. Register the user by making client-side API call to [Create retail user](#tag/User/paths/~1api~1v1~1user~1retail/post) with necessary data.\n```bash\n     curl --request POST \\\n     --url https://api-business.wirexpaychain.tech/api/v1/user/retail \\\n     --header 'Authorization: Bearer {your_privy_access_token}' \\\n     --header 'Identity: Bearer {your_privy_identity_token}' \\\n     --header 'Content-Type: application/json' \\\n     --data '{\n     \"country\": \"FR\"\n     }'\n ```\n  4. Exchange Privy tokens for a **Wirex User Token** (see [Authorization > Wirex User Token](#tag/Authorization/Wirex-User-Token)).\n  5. Use the Wirex User Token to complete onboarding and initiate other user-specific operations (e.g., card activation, transaction initiation).\n\n### Best For\nPartners looking for a seamless, secure, and low-maintenance user onboarding experience.\n\n---\n\nBy supporting both **backend-driven** and **embedded identity provider** flows, the Wirex BaaS API gives you the flexibility to tailor user onboarding to your product’s architecture—without compromising on security or decentralization.",
      "name": "Onboarding/OffChain"
    }
  ],
  "x-readme": {}
}
````