> ## Documentation Index > Fetch the complete documentation index at: https://docs.bitrobot.ai/llms.txt > Use this file to discover all available pages before exploring further. # Confirm a wallet connection > Confirms the wallet the signed-in user has on your subnet for a [BitRobot Connect](/bitrobot-connect) request. Call this from your backend when the user presses **Connect** on your connect page. Send the `request_id` and `nonce` you stored when the user landed on the page, and the user's wallet address. Redirect the browser to the `return_url` in the response verbatim, fragment included. Branch on `auth_code`, not the HTTP status: a `409 already_confirmed` response can also carry `auth_code`. Never log, display, or store `auth_code`. If you send an `Idempotency-Key` header, use a new value on every attempt, including retries. Limit: 120 requests per minute per API key. ## OpenAPI ````yaml post /subnets/{subnet_id}/connect/confirm openapi: 3.0.3 info: title: BitRobot API description: > The BitRobot API allows you to interact with the BitRobot platform, including event tracking, task management, and points distribution. ## Authentication All requests require authentication using an API key. Include your API key in the `Authorization` header: ``` Authorization: Bearer brb_your_api_key_here ``` ## Identifiers All resource identifiers in the API use the ULID format (Universally Unique Lexicographically Sortable Identifier). version: 1.0.0 contact: name: BitRobot API Support servers: - url: https://api-stage.bitrobot.ai description: Staging server - url: https://api.bitrobot.ai description: Production server security: [] tags: - name: Events description: > Event tracking and management endpoints. Events allow you to track important actions and state changes in your subnet, including task execution (rides) and points distribution. - name: Subnets description: > Subnet-scoped integration endpoints for balances, points history, and conversion history. - name: Connect description: > BitRobot Connect endpoints for linking a user's subnet wallet to their BitRobot account. See the [BitRobot Connect](/bitrobot-connect) guide. paths: /subnets/{subnet_id}/connect/confirm: post: tags: - Connect summary: Confirm a wallet connection description: >- Confirms the wallet the signed-in user has on your subnet for a [BitRobot Connect](/bitrobot-connect) request. Call this from your backend when the user presses **Connect** on your connect page. Send the `request_id` and `nonce` you stored when the user landed on the page, and the user's wallet address. Redirect the browser to the `return_url` in the response verbatim, fragment included. Branch on `auth_code`, not the HTTP status: a `409 already_confirmed` response can also carry `auth_code`. Never log, display, or store `auth_code`. If you send an `Idempotency-Key` header, use a new value on every attempt, including retries. Limit: 120 requests per minute per API key. operationId: confirmWalletConnection parameters: - name: subnet_id in: path required: true description: >- The unique identifier of the subnet (ULID format). Must match the subnet your API key was created for. schema: type: string pattern: ^[0-9A-HJKMNP-TV-Z]{26}$ example: 01ARZ3NDEKTSV4RRFFQ69G5FAV requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ConnectConfirmRequest' examples: withSubnetUserId: summary: Confirm with your own user id value: request_id: 01ARZ3NDEKTSV4RRFFQ69G5FAV nonce: Qm3xk7w2Zr9vL1nB8pT4yH6sD0aF5cG2jK8mN1oP3qR wallet_address: HN7cABqLq46Es1jh92dQQisAq662SmxELLLsHHe4YWrH subnet_user_id: user_8f2c1 minimal: summary: Minimal value: request_id: 01ARZ3NDEKTSV4RRFFQ69G5FAV nonce: Qm3xk7w2Zr9vL1nB8pT4yH6sD0aF5cG2jK8mN1oP3qR wallet_address: HN7cABqLq46Es1jh92dQQisAq662SmxELLLsHHe4YWrH responses: '200': description: >- Wallet recorded on the request. Redirect the browser to `return_url` verbatim, fragment included. content: application/json: schema: $ref: '#/components/schemas/ConnectConfirmResponse' example: status: success return_url: >- https://app.bitrobot.ai/connect/callback?request_id=01ARZ3NDEKTSV4RRFFQ69G5FAV#ac=8Kd2mQx7f3RcVn0Pz_s1TgW6bHuJ4eLpAo9iNr-k5Zw auth_code: 8Kd2mQx7f3RcVn0Pz_s1TgW6bHuJ4eLpAo9iNr-k5Zw expires_at: '2026-09-02T10:30:00Z' '400': description: Bad request - No subnet with this subnet_id exists content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Invalid subnet_id '401': description: Unauthorized - Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Invalid or missing API key '403': description: >- Forbidden - The API key belongs to a different subnet, or the person who created the key is no longer an admin of the subnet content: application/json: schema: $ref: '#/components/schemas/Error' examples: wrongSubnet: summary: Key minted for a different subnet value: error: API key not authorized for this subnet notAuthorized: summary: Key creator is no longer a subnet admin value: error: Not authorized '404': description: >- Not found - No connect request with this id exists for your subnet, or BitRobot Connect is not enabled for the subnet content: application/json: schema: $ref: '#/components/schemas/ConnectConfirmError' examples: requestNotFound: summary: Unknown request_id, or Connect not enabled for the subnet value: error: Connect request not found reason: request_not_found '409': description: >- Conflict - The request already has a wallet from an earlier confirm. When `auth_code` is present, redirect to `return_url` as on a `200`. content: application/json: schema: $ref: '#/components/schemas/ConnectConfirmConflict' examples: alreadyConfirmedReissued: summary: Retry - a new authorization code is issued value: error: Connect request already confirmed reason: already_confirmed return_url: >- https://app.bitrobot.ai/connect/callback?request_id=01ARZ3NDEKTSV4RRFFQ69G5FAV#ac=Ln4tW8zQ0aYc6ReM2pKj7xVhB1sDfG5-ToI3Zn_wXy9 auth_code: Ln4tW8zQ0aYc6ReM2pKj7xVhB1sDfG5-ToI3Zn_wXy9 expires_at: '2026-09-02T10:30:00Z' alreadyConfirmedFinished: summary: Request already completed or expired - no authorization code value: error: Connect request already confirmed reason: already_confirmed return_url: >- https://app.bitrobot.ai/connect/callback?request_id=01ARZ3NDEKTSV4RRFFQ69G5FAV '410': description: Gone - The request expired before it received a wallet content: application/json: schema: $ref: '#/components/schemas/ConnectConfirmError' examples: requestExpired: summary: Expired request value: error: Connect request has expired reason: request_expired '422': description: >- Unprocessable Content - The nonce does not match, the wallet address is not a Solana public key, or wallet_signature does not verify content: application/json: schema: $ref: '#/components/schemas/ConnectConfirmError' examples: nonceMismatch: summary: Wrong nonce value: error: Nonce does not match this request reason: nonce_mismatch invalidAddress: summary: Not a Solana public key value: error: >- wallet_address must be a base58-encoded 32-byte Solana public key reason: invalid_address invalidSignature: summary: wallet_signature does not verify value: error: wallet_signature does not verify for this wallet reason: invalid_signature '429': description: >- Too many requests - More than 120 confirms per minute on one API key; the Retry-After header says how long to wait content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Rate limit exceeded. Please slow down. security: - BearerAuth: [] components: schemas: ConnectConfirmRequest: title: Connect Confirm Request type: object required: - request_id - nonce - wallet_address properties: request_id: type: string pattern: ^[0-9A-HJKMNP-TV-Z]{26}$ description: >- The `request_id` from your connect URL's query string, read from your server-side session. example: 01ARZ3NDEKTSV4RRFFQ69G5FAV nonce: type: string description: >- The `nonce` from your connect URL's query string, read from your server-side session. example: Qm3xk7w2Zr9vL1nB8pT4yH6sD0aF5cG2jK8mN1oP3qR wallet_address: type: string description: >- The user's Solana wallet address on your subnet (base58, decodes to 32 bytes). example: HN7cABqLq46Es1jh92dQQisAq662SmxELLLsHHe4YWrH subnet_user_id: type: string description: >- Optional. Your own identifier for the user. Truncated to 128 characters. Do not include personal data. example: user_8f2c1 wallet_signature: type: string maxLength: 128 description: >- Optional. An Ed25519 signature by the user's wallet key over the UTF-8 string `bitrobot-connect::`, base58-encoded. When present, this connection replaces an unproven connection another account holds for the same address on your subnet. example: >- 4vJ9JU1bJJE96FbKCbHmJmL8nT2rZ7yQpF1sWx3dGk8mQ2hVnA5cRt7uYbXe1PqLzMw9NfKd3SgHj6TrBv2CaEyU example: request_id: 01ARZ3NDEKTSV4RRFFQ69G5FAV nonce: Qm3xk7w2Zr9vL1nB8pT4yH6sD0aF5cG2jK8mN1oP3qR wallet_address: HN7cABqLq46Es1jh92dQQisAq662SmxELLLsHHe4YWrH subnet_user_id: user_8f2c1 ConnectConfirmResponse: title: Connect Confirm Response type: object required: - status - return_url - auth_code - expires_at properties: status: type: string enum: - success return_url: type: string format: uri description: >- Redirect the user's browser here verbatim, fragment included. Check that the scheme is `http` or `https` first. example: >- https://app.bitrobot.ai/connect/callback?request_id=01ARZ3NDEKTSV4RRFFQ69G5FAV#ac=8Kd2mQx7f3RcVn0Pz_s1TgW6bHuJ4eLpAo9iNr-k5Zw auth_code: type: string description: >- The authorization code, also present in `return_url`'s fragment. Check for its presence. Never log, display, or store it. Single-use; expires 5 minutes after it is issued. example: 8Kd2mQx7f3RcVn0Pz_s1TgW6bHuJ4eLpAo9iNr-k5Zw expires_at: type: string format: date-time description: >- When the connect request expires: 30 minutes after the user pressed **Connect** next to your subnet on their BitRobot profile page. example: '2026-09-02T10:30:00Z' example: status: success return_url: >- https://app.bitrobot.ai/connect/callback?request_id=01ARZ3NDEKTSV4RRFFQ69G5FAV#ac=8Kd2mQx7f3RcVn0Pz_s1TgW6bHuJ4eLpAo9iNr-k5Zw auth_code: 8Kd2mQx7f3RcVn0Pz_s1TgW6bHuJ4eLpAo9iNr-k5Zw expires_at: '2026-09-02T10:30:00Z' Error: type: object required: - error properties: error: type: string description: Description of the error example: Invalid or missing API key ConnectConfirmError: title: Connect Confirm Error type: object required: - error - reason properties: error: type: string description: >- Human-readable description of the error, suitable for showing to the user. example: Connect request not found reason: type: string enum: - request_not_found - request_expired - nonce_mismatch - invalid_address - invalid_signature - invalid_request description: >- Machine-readable reason code. `request_not_found`: no request with this id exists for your subnet, or BitRobot Connect is not enabled for the subnet. `request_expired`: the request expired before it received a wallet. `nonce_mismatch`: the nonce does not match the request. `invalid_address`: `wallet_address` is not a base58 32-byte Solana public key. `invalid_signature`: `wallet_signature` does not verify for that address. `invalid_request`: the request failed validation. example: request_not_found ConnectConfirmConflict: title: Connect Confirm Conflict type: object required: - error - reason - return_url properties: error: type: string description: >- Human-readable description of the error, suitable for showing to the user. example: Connect request already confirmed reason: type: string enum: - already_confirmed description: Machine-readable reason code. example: already_confirmed return_url: type: string format: uri description: >- When `auth_code` is present, redirect the user's browser here verbatim, fragment included. Check that the scheme is `http` or `https` first. example: >- https://app.bitrobot.ai/connect/callback?request_id=01ARZ3NDEKTSV4RRFFQ69G5FAV#ac=Ln4tW8zQ0aYc6ReM2pKj7xVhB1sDfG5-ToI3Zn_wXy9 auth_code: type: string description: >- A new authorization code, also present in `return_url`'s fragment. Check for its presence. Never log, display, or store it. Single-use; expires 5 minutes after it is issued. example: Ln4tW8zQ0aYc6ReM2pKj7xVhB1sDfG5-ToI3Zn_wXy9 expires_at: type: string format: date-time description: When the connect request expires. example: '2026-09-02T10:30:00Z' securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: API Key description: | API key authentication. Your API key should start with `brb_`. Example: `Authorization: Bearer brb_1234567890abcdef` ````