BitRobot Connect

​

Prerequisites

• Your subnet is registered and you know its Subnet ID.
• An API key for the subnet, kept server-side.
• A connect URL you host: an https page on your own domain, with no query string or fragment, behind your normal login. Send that URL to the BitRobot team.

​

How it works

1. The user presses Connect next to your subnet on their BitRobot profile page. BitRobot redirects the browser to your connect URL with request_id and nonce in the query string.
2. Your connect page stores request_id and nonce in the user’s server-side session and shows a Connect button.
3. When the user presses Connect, your backend calls the confirm endpoint with your API key and the user’s wallet address.
4. Your backend redirects the browser to the return_url from the response. BitRobot completes the connection as the page loads.

​

Step 1 — Build the connect page

https://your-subnet.com/bitrobot/connect?request_id=01ARZ3NDEKTSV4RRFFQ69G5FAV&nonce=Qm3xk7w2Zr9vL1nB8pT4yH6sD0aF5cG2jK8mN1oP3qR

1. Require login. If the user is signed out, send them through login and back to this URL with the query string intact. See Returning from login.
2. Store request_id and nonce in the server-side session for the signed-in user.
3. Show the user’s wallet address and a Connect button that POSTs to your confirm handler.

router.get("/bitrobot/connect", requireLogin, (req, res) => {
  const { request_id: requestId, nonce } = req.query;
  if (typeof requestId !== "string" || typeof nonce !== "string") {
    return res.status(400).send("Missing request_id or nonce");
  }

  req.session.bitrobotConnect = { requestId, nonce };
  res.render("bitrobot-connect", { walletAddress: req.user.walletAddress });
});

​

Step 2 — Confirm the wallet

POST https://api.bitrobot.ai/subnets/{subnet_id}/connect/confirm
Authorization: Bearer brb_your_api_key
Content-Type: application/json

{
  "request_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "nonce": "Qm3xk7w2Zr9vL1nB8pT4yH6sD0aF5cG2jK8mN1oP3qR",
  "wallet_address": "HN7cABqLq46Es1jh92dQQisAq662SmxELLLsHHe4YWrH"
}

{
  "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"
}

​

Step 3 — Redirect to BitRobot

• auth_code is present. Clear the session values, check that return_url starts with https:// or http://, and redirect the browser to it. Use a 303 redirect from your handler. For a client-side page, return return_url from your handler and call window.location.replace(url).
• auth_code is absent. Show an error page with the error message from the response. Template: Error page.

router.post("/bitrobot/connect/confirm", requireLogin, async (req, res) => {
  const pending = req.session.bitrobotConnect;
  if (!pending) return res.status(400).send("No connection in progress");

  const response = await fetch(`${BITROBOT_API_BASE}/subnets/${BITROBOT_SUBNET_ID}/connect/confirm`, {
    method: "POST",
    headers: { Authorization: `Bearer ${BITROBOT_API_KEY}`, "Content-Type": "application/json" },
    body: JSON.stringify({
      request_id: pending.requestId,
      nonce: pending.nonce,
      wallet_address: req.user.walletAddress,
    }),
  });
  const body = await response.json();

  if (!body.auth_code || !/^https?:\/\//.test(body.return_url)) {
    return res.status(400).render("bitrobot-connect-error", { error: body.error });
  }

  delete req.session.bitrobotConnect;
  res.redirect(303, body.return_url);
});

​

Errors

{
  "error": "Connect request not found",
  "reason": "request_not_found"
}

​

Test on staging

1. Ask the BitRobot team to register your subnet on staging and use the Subnet ID they issue. Create a staging API key and set BITROBOT_API_BASE=https://api-stage.bitrobot.ai.
2. Call the confirm endpoint with a made-up request_id. A 404 request_not_found confirms your key and Subnet ID are valid.
   curl -sS -X POST "https://api-stage.bitrobot.ai/subnets/$BITROBOT_SUBNET_ID/connect/confirm" \
     -H "Authorization: Bearer $BITROBOT_API_KEY" -H "Content-Type: application/json" \
     -d '{"request_id":"01ARZ3NDEKTSV4RRFFQ69G5FAV","nonce":"test","wallet_address":"HN7cABqLq46Es1jh92dQQisAq662SmxELLLsHHe4YWrH"}'
   
3. Send the BitRobot team your staging connect URL and wait for them to enable it.
4. Sign in at https://stage.bitrobot.ai, open your profile page, press Connect next to your subnet, then press Connect on your page. The subnet shows Connected.
5. Send a Subnet Points grant by wallet_address for that wallet. The points appear on the user’s dashboard.

​

Next steps