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
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
When a new user is created on supported chains, you will receive a Base64 encoded challenge, which resembles the following:
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:
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
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
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>.
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
{
"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"
}
POST /v1/customers/{customerId}/challenge/sign HTTP/1.1
Host: api.offblocks.xyz
Authorization: Bearer YOUR_SECRET_TOKEN
Signature: text
Signature-Input: text
Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000
Content-Digest: text
Content-Type: application/json
Accept: */*
Content-Length: 415
{
"ownerId": "eip155:1:0xab16a96D359eC26a11e2C2b3d8f8B8942d5Bfcdb",
"challenge": "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUZZd0VBWUhLb1pJemowQ0FRWUZLNEVFQUFvRFFnQUUzTEw1RldmVFgvL3BJaXNEL0xneFVIT2lxdlFTSUVWTgpGekloOTdLZXBlWk1iZVZsUGd1akZ4Yk5MN2x1ZVhRQnBpUWUzNmZLN0xSbXZNNHdEaWZFTkE9PQotLS0tLUVORCBQVUJMSUMgS0VZLS0tLS0=",
"signature": "IfvwaW1eCqLvQaK0/7YjvK8HBGHWHPclHHQWH4L+w6Q3CFS8CjSzq0h8G8AhzTGMc0xRrik3TyvrDm8t1JtL9Bw="
}
GET /v1/customers/{customerId}/challenge HTTP/1.1
Host: api.offblocks.xyz
Authorization: Bearer YOUR_SECRET_TOKEN
Signature: text
Signature-Input: text
Accept: */*
