4️⃣Customer Creation

This step assumes you have successfully authenticated your API credentials using Authentication and have followed Request Signatures and Idempotency guides to configure your requests

Now that you can make authenticated requests to the API, you are officially ready to onboard new customers with our platform. To do so, you need to use /customers POST request.

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-11-21T06:36:32.589Z",
  "updatedAt": "2024-11-21T06:36:32.589Z",
  "challenge": "Ynl0ZXM="
}

Specified chainId is expected to follow the convention outlined in Account Identifier. For example, in order to onboard a customer using zkSync Era wallet with address 0x22227A31dd842196A246d8f3b775998560eAa61d on Goerli Testnet, you can submit a following request:

{
  "chainId": "eip155:280:0x22227A31dd842196A246d8f3b775998560eAa61d",
  "externalId": "27c9aa3b-f12d-43b9-8e91-5264ccc998de"
}

If a customer with specified chainId and externalId is not onboarded in our system yet, you will receive a response with status 201 (Created) which looks similar to the following:

{
    "chainId": "eip155:280:0x22227A31dd842196A246d8f3b775998560eAa61d",
    "challenge": "YXBpLnNhbmRib3gub2ZmYmxvY2tzLnh5eiB3YW50cyB5b3UgdG8gc2lnbiBpbiB3aXRoIHlvdXIgRXRoZXJldW0gYWNjb3VudDoKMHg0MzE1OGY0NWI1RWJEN2IxMTc5MTMwMTMwREYwMDM5MzkyOEMyNjkxCgpPZmZCbG9ja3Mgd2FudHMgdG8gdmVyaWZ5IG93bmVyc2hpcCBvZiB5b3VyIHdhbGxldC4gQnkgY29ubmVjdGluZyB5b3VyIHdhbGxldCBhbmQgdXNpbmcgT2ZmQmxvY2tzLCB5b3UgYWdyZWUgdG8gb3VyIFRlcm1zIG9mIHNlcnZpY2VzIGFuZCBQcml2YWN5IFBvbGljeQoKVVJJOiBodHRwczovL2FwaS5zYW5kYm94Lm9mZmJsb2Nrcy54eXoKVmVyc2lvbjogMQpDaGFpbiBJRDogMjgwCk5vbmNlOiA1dWZvaUVxRGFGdm1mbzc4Cklzc3VlZCBBdDogMjAyNC0wMS0xN1QxODoyMTo1M1o=",
    "createdAt": "2024-01-12T14:53:02.65345725Z",
    "externalId": "27c9aa3b-f12d-43b9-8e91-5264ccc998de",
    "id": "04c5851c-4386-5bd9-9f89-08312f8aee3a",
    "status": "initiating",
    "updatedAt": "2024-01-12T14:53:02.65345725Z"
}

If everything went well, you will receive a customer challenge to sign as a base64 encoded string. This is required to proceed to verification stage. Please, follow Sign in With X guide for more details on signing a customer challenge.

In order to submit a signed challenge, use a POST request to /customers/{customerId}/challenge/sign 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();

{
  "ownerId": "eip155:280:0x43158f45b5EbD7b1179130131DF00393928C2691",
  "challenge": "YXBpLnNhbmRib3gub2ZmYmxvY2tzLnh5eiB3YW50cyB5b3UgdG8gc2lnbiBpbiB3aXRoIHlvdXIgRXRoZXJldW0gYWNjb3VudDoKMHg0MzE1OGY0NWI1RWJEN2IxMTc5MTMwMTMwREYwMDM5MzkyOEMyNjkxCgpPZmZCbG9ja3Mgd2FudHMgdG8gdmVyaWZ5IG93bmVyc2hpcCBvZiB5b3VyIHdhbGxldC4gQnkgY29ubmVjdGluZyB5b3VyIHdhbGxldCBhbmQgdXNpbmcgT2ZmQmxvY2tzLCB5b3UgYWdyZWUgdG8gb3VyIFRlcm1zIG9mIHNlcnZpY2VzIGFuZCBQcml2YWN5IFBvbGljeQoKVVJJOiBodHRwczovL2FwaS5zYW5kYm94Lm9mZmJsb2Nrcy54eXoKVmVyc2lvbjogMQpDaGFpbiBJRDogMjgwCk5vbmNlOiA1dWZvaUVxRGFGdm1mbzc4Cklzc3VlZCBBdDogMjAyNC0wMS0xN1QxODoyMTo1M1o=",
  "signature": "MHg4M2IxM2RhYjE2MjI3MjAxMWQzMzQ4NDFkZjE5NTQ1MjUwNDI1NjczMjhhZDdjMDVjOTYyYjAwNWVlZDg3MGI2NDhjMjA0ZjBiZmZjZjUyYjM3NTE0MGIwYzg0OTA4ZTQ2MzMyNWIxZGZlNWJiYjAzMjU5NzYyNDgyODM0YWYzNzFi"
}

Please, not that the signature also must be a base64 encoded string. If signature is verified, you will receive an empty response with status code 204 (No Content).

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