gobtc payDocs

Authentication

Challenge-response authentication. Request a message to sign with the wallet key, exchange the signature for a JWT pair, and refresh it.

Get sign-in challenge

POSThttps://api.gobtcpay.com/public/api/v1.2/instant/auth/get-data-to-sign

Starts the authentication challenge. Returns a one-time messageToSign and a challengeId bound to the supplied public key (valid until expiresAt, ~5 min). Sign messageToSign verbatim with the corresponding private key using Bitcoin message signing (secp256k1 ECDSA), then exchange it for tokens via Get access tokens.

Body required

application/json
userPubKeyHexstringrequired

Public key of the user's Bitcoin wallet to authenticate, compressed secp256k1 key, hex (33 bytes / 66 chars).

Example:02a1633cafcc01ebfb6d78e39f687a1f0995c62fc95f51ead10a02ee0be551b5dc

Responses

idstringrequired
Example:3fa85f64-5717-4562-b3fc-2c963f66afa6
resultobjectrequired
POST /instant/auth/get-data-to-sign
cURL
curl -X POST "$BASE_URL/instant/auth/get-data-to-sign" \
  -H "Content-Type: application/json" \
  -d '{
  "userPubKeyHex": "02a1633cafcc01ebfb6d78e39f687a1f0995c62fc95f51ead10a02ee0be551b5dc"
}'
200 Successful response
JSON
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "challengeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "messageToSign": "instant-go login;pubkey=02a1633c;nonce=Zm9vYmFyYmF6;issuedAt=2026-06-11T10:00:00.000Z;expiresAt=2026-06-11T10:05:00.000Z",
      "expiresAt": 1718012345
    }
  }
}

Get access tokens

POSThttps://api.gobtcpay.com/public/api/v1.2/instant/auth/get-jwt

Completes the authentication challenge. Submit the challengeId from Get sign-in challenge together with the hex-encoded 64-byte compact signature of messageToSign. Returns a short-lived accessToken (send it as Authorization: Bearer <accessToken>) and a long-lived refreshToken.

Body required

application/json
challengeIdstringrequired

The challengeId returned by Get sign-in challenge (/instant/auth/get-data-to-sign).

Example:3fa85f64-5717-4562-b3fc-2c963f66afa6
signaturestringrequired

Hex-encoded 64-byte compact signature of the messageToSign from Get sign-in challenge.

Example:4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7a…

Responses

idstringrequired
Example:3fa85f64-5717-4562-b3fc-2c963f66afa6
resultobjectrequired
POST /instant/auth/get-jwt
cURL
curl -X POST "$BASE_URL/instant/auth/get-jwt" \
  -H "Content-Type: application/json" \
  -d '{
  "challengeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "signature": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b"
}'
200 Successful response
JSON
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "accessToken": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq",
      "refreshToken": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq"
    }
  }
}

Refresh access tokens

POSThttps://api.gobtcpay.com/public/api/v1.2/instant/auth/refresh-jwt

Exchanges a valid refresh token for a fresh accessToken / refreshToken pair without repeating the signing challenge. Send the refresh token as Authorization: Bearer <refreshToken> with an empty body.

Authorization: walletAuth

Responses

idstringrequired
Example:3fa85f64-5717-4562-b3fc-2c963f66afa6
resultobjectrequired
POST /instant/auth/refresh-jwt
cURL
curl -X POST "$BASE_URL/instant/auth/refresh-jwt" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
200 Successful response
JSON
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": {
    "$case": "success",
    "success": {
      "accessToken": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq",
      "refreshToken": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq"
    }
  }
}