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 /customersPOST request.
Create new customer
post
/customers
Creates new customer and generates a cryptographic challenge to verify ownership of blockchain account
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Header parameters
SignaturestringRequired
HTTP message signature
Signature-InputstringRequired
HTTP message signature input
Idempotency-Keystring · uuidRequired
Idempotency key (UUID)
Content-DigeststringRequired
Content digest
Body
chainIdstringRequired
Unique customer ID in a form of a valid on-chain address. This would normally correspond to customer's EOA wallet address
Unique customer ID in a form of an external identifier. This would normally correspond to customer's ID in your system
Responses
201
Successful operation
application/json
400
Invalid request
401
Not authorised
409
Customer already exists
500
Internal error
post
/customers
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:
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:
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
post
/customers/{customerId}/challenge/sign
Signs previously issued challenge to verify customer's ownership of their blockchain account
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
customerIdstring · uuidRequired
Unique customer ID
Header parameters
SignaturestringRequired
HTTP message signature
Signature-InputstringRequired
HTTP message signature input
Idempotency-Keystring · uuidRequired
Idempotency key (UUID)
Content-DigeststringRequired
Content digest
Body
Cryptographic signature generated using owner's EOA private key according to chain-specific algorithm. Signature is used for signing on-chain transactions such as creating a new account, authorising a recurring payment or setting up spending limits
ownerIdstringRequired
Unique signer account ID in a form of a valid on-chain address
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
get
/customers/{customerId}/challenge
Retrieves challenge to verify customer's ownership of their blockchain account
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
GET /v1/customers/{customerId}/challenge HTTP/1.1
Host: api.offblocks.xyz
Authorization: Bearer YOUR_SECRET_TOKEN
Signature: text
Signature-Input: text
Accept: */*
