📲Sign in With X

This functionality is currently only supported on EVM networks and is 100% compliant with EIP-4361 (Sign in With Ethereum). We will be adding support for more networks soon.

To verify a customer's externally-owned account ownership, we require a challenge to be signed with the private key. This mechanism is outlined in CAIP-122, originally known as "Sign in With Ethereum" (SIWE) but expanded to support other blockchains. When a new customer object is created in our system, we generate a challenge following the standardised structure, expecting it to be signed and verified before proceeding with user onboarding. The challenge returned by the endpoint is a Base64-encoded string.

Create new customer

Creates new customer and generates a cryptographic challenge to verify ownership of blockchain account

POSThttps://api.offblocks.xyz/v1/customers

Authorization

bearerAuth

Header parameters

Body

application/json

chainId*BlockchainAccountId (string)

Universal unique on-chain identifier of the account following CAIP-10 specification

externalId*string

Unique customer ID in a form of an external identifier. This would normally correspond to customer's ID in your system

Response

201400401409500

Successful operation

Body

application/json

id*CustomerId (string (uuid))

externalId*string

Unique customer ID in a form of an external ID

chainId*BlockchainAccountId (string)

Universal unique on-chain identifier of the account following CAIP-10 specification

status*CustomerStatus (enum)

Customer status

initiatingscreeningverifyingrejectedactiveinactive

createdAt*DateTime (string (date-time))

ISO-8601 timestamp

updatedAt*DateTime (string (date-time))

ISO-8601 timestamp

challenge*string (byte)

Base64 encoded message provided by this API for owner to sign

Request

JavaScriptCurlPython

const response = await fetch('https://api.offblocks.xyz/v1/customers', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Signature": "text",
      "Signature-Input": "text",
      "Idempotency-Key": "123e4567-e89b-12d3-a456-426614174000",
      "Content-Digest": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "chainId": "text",
      "externalId": "text"
    }),
});
const data = await response.json();

Response

201

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "externalId": "text",
  "chainId": "text",
  "status": "initiating",
  "createdAt": "2024-12-22T06:06:33.020Z",
  "updatedAt": "2024-12-22T06:06:33.020Z",
  "challenge": "Ynl0ZXM="
}

When a new user is created on supported chains, you will receive a Base64 encoded challenge, which resembles the following:

api.sandbox.offblocks.xyz wants you to sign in with your Ethereum account:
0x43158f45b5EbD7b1179130130DF00393928C2691

OffBlocks wants to verify ownership of your wallet. By connecting your wallet and using OffBlocks, you agree to our Terms of services and Privacy Policy

URI: https://api.sandbox.offblocks.xyz
Version: 1
Chain ID: 300
Nonce: 5ufoiEqDaFvmfo78
Issued At: 2024-01-17T18:21:53Z

In order to proceed with ownership verification, your customer needs to sign this challenge with their private key. Please, follow SIWE documentation to learn more about signing SIWE challenges using community supported libraries. For testing purposes, you can use MyCrypto signing tools to sign a challenge for test accounts.

If everything was successful, you will have a HEX-formatted signature ready to be submitted to our API. For example, if using MyCrypto, it will produce a following message for the above challenge:

{
  "address": "0x43158f45b5EbD7b1179130130DF00393928C2691",
  "msg": "api.sandbox.offblocks.xyz wants you to sign in with your Ethereum account:\n0x43158f45b5EbD7b1179130130DF00393928C2691\n\nOffBlocks wants to verify ownership of your wallet. By connecting your wallet and using OffBlocks, you agree to our Terms of services and Privacy Policy\n\nURI: https://api.sandbox.offblocks.xyz\nVersion: 1\nChain ID: 300\nNonce: 5ufoiEqDaFvmfo78\nIssued At: 2024-01-17T18:21:53Z",
  "sig": "0xd2472857a11a29b612fda39b3a381cc88a8e6d085333cb7e2536ea38e71664be5e88ada8f5de966eff4f7c9cf59429b9a24814d878e779db34b612d4091c26ba1c",
  "version": "2"
}

To submit a signed challenge, please encode a HEX signature as Base64 string and send it using the corresponding endpoint.

Sign previously issued customer challenge

Signs previously issued challenge to verify customer's ownership of their blockchain account

POSThttps://api.offblocks.xyz/v1/customers/{customerId}/challenge/sign

Authorization

bearerAuth

Path parameters

customerId*CustomerId (string (uuid))

ID of customer to be challenged

Header parameters

Body

application/json

ownerId*BlockchainAccountId (string)

Universal unique on-chain identifier of the account following CAIP-10 specification

challenge*string (byte)

Original base64 encoded challenge provided by this API for owner to sign

signature*string (byte)

Base64 encoded signature

Response

204400401404409500

Successful operation

Request

JavaScriptCurlPython

const response = await fetch('https://api.offblocks.xyz/v1/customers/{customerId}/challenge/sign', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Signature": "text",
      "Signature-Input": "text",
      "Idempotency-Key": "123e4567-e89b-12d3-a456-426614174000",
      "Content-Digest": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "ownerId": "text",
      "challenge": "Ynl0ZXM=",
      "signature": "Ynl0ZXM="
    }),
});
const data = await response.json();

If, for any reason, the original challenge is lost or cannot be signed immediately, you can fetch it again using a dedicated endpoint. If we encounter an error during signature validation via /sign endpoint, a new challenge will be issued for you to retrieve.

We enforce a 1 hour expiration window via our API for all issued challenges for security purposes. If a challenge hasn't been signed within 1 hour from issue, we will generate a new one and make it available through this endpoint.

Retrieve customer challenge

Retrieves challenge to verify customer's ownership of their blockchain account

GEThttps://api.offblocks.xyz/v1/customers/{customerId}/challenge

Authorization

bearerAuth

Path parameters

customerId*CustomerId (any)

Unique customer ID

Header parameters

Response

200400401404500

Successful operation

Body

application/json

challenge*string (byte)

Base64 encoded message provided by this API for owner to sign

Request

JavaScriptCurlPython

const response = await fetch('https://api.offblocks.xyz/v1/customers/{customerId}/challenge', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer JWT",
      "Signature": "text",
      "Signature-Input": "text"
    },
});
const data = await response.json();

Response

200

{
  "challenge": "Ynl0ZXM="
}