OffBlocks
  • πŸ‘‹Welcome to OffBlocks
  • Overview
    • πŸ’‘What we do
    • ✨Core Concepts
    • πŸ“œWhitepaper
    • ⛓️Supported Blockchains and Assets
    • ❔FAQ
  • Developer Guides
    • πŸ—οΈSystem Architecture
    • βš™οΈAPI Integration
      • πŸš€Getting Started
      • πŸ“―Postman
      • πŸ”‘Authentication
      • πŸ”Request Signatures
      • πŸ†”Idempotency
      • ⛓️Blockchain Identifiers
      • πŸ“’Blockchain Updates
      • πŸ“²Sign in With X
      • πŸ’°Fees
      • πŸ•ΉοΈSimulator
      • πŸ”’API Reference
        • πŸ¦Έβ€β™‚οΈCustomers
        • 🏦Accounts
        • πŸ’³Cards
        • πŸ”ƒTransactions
        • πŸͺWebhooks
        • πŸ•ΉοΈSimulator
        • πŸš‚Engine
      • ⏭️States and Transitions
        • πŸ¦Έβ€β™‚οΈCustomer States
        • 🏦Account States
        • πŸ’³Card States
        • πŸ”‘Authorisation States
        • πŸ”ƒTransaction States
    • 🧬Smart Contracts
      • OffBlocksEscrow.sol
      • OffBlocksSmartWalletFactory.sol
      • OffBlocksSmartWallet.sol
      • PendingWithdrawal.sol
      • Interfaces
    • πŸ”’Step-by-step Guide
      • 1️⃣API Credentials
      • 2️⃣Authentication
      • 3️⃣Request Preparation
      • 4️⃣Customer Creation
      • 5️⃣Customer Verification
      • 6️⃣Account Creation
      • 7️⃣Card Issuance
      • 8️⃣Card Authorisations
      • 9️⃣Webhooks
  • Use Cases
    • πŸ’°Wallet Providers
    • πŸ§‘β€πŸŒΎDeFi Apps
    • 🏦Neo-banks and FinTechs
Powered by GitBook
On this page
  1. Developer Guides
  2. Step-by-step Guide

Customer Creation

PreviousRequest PreparationNextCustomer Verification

Last updated 1 year ago

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.

Specified chainId is expected to follow the convention outlined in . 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.

{
  "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.

πŸ”’
4️⃣
Account Identifier

Retrieve customer challenge

get

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

Authorizations
Path parameters
customerIdstring Β· uuidRequired

Unique customer ID

Header parameters
SignaturestringRequired

HTTP message signature

Signature-InputstringRequired

HTTP message signature input

Responses
200
Successful operation
application/json
400
Invalid request
401
Not authorised
404
Customer not found
500
Internal error
get
GET /v1/customers/{customerId}/challenge HTTP/1.1
Host: api.offblocks.xyz
Authorization: Bearer JWT
Signature: text
Signature-Input: text
Accept: */*
{
  "challenge": "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUZZd0VBWUhLb1pJemowQ0FRWUZLNEVFQUFvRFFnQUUzTEw1RldmVFgvL3BJaXNEL0xneFVIT2lxdlFTSUVWTgpGekloOTdLZXBlWk1iZVZsUGd1akZ4Yk5MN2x1ZVhRQnBpUWUzNmZLN0xSbXZNNHdEaWZFTkE9PQotLS0tLUVORCBQVUJMSUMgS0VZLS0tLS0="
}
  • POSTCreate new customer
  • POSTSign previously issued customer challenge
  • GETRetrieve customer challenge

Create new customer

post

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

Authorizations
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

Example: eip155:1:0xab16a96D359eC26a11e2C2b3d8f8B8942d5Bfcdb
externalIdstringRequired

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
Responseall of
and
400
Invalid request
401
Not authorised
409
Customer already exists
500
Internal error
post
POST /v1/customers HTTP/1.1
Host: api.offblocks.xyz
Authorization: Bearer JWT
Signature: text
Signature-Input: text
Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000
Content-Digest: text
Content-Type: application/json
Accept: */*
Content-Length: 85

{
  "chainId": "eip155:1:0xab16a96D359eC26a11e2C2b3d8f8B8942d5Bfcdb",
  "externalId": "text"
}
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "externalId": "text",
  "chainId": "eip155:1:0xab16a96D359eC26a11e2C2b3d8f8B8942d5Bfcdb",
  "status": "initiating",
  "createdAt": "2025-05-09T06:31:16.216Z",
  "updatedAt": "2025-05-09T06:31:16.216Z",
  "challenge": "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUZZd0VBWUhLb1pJemowQ0FRWUZLNEVFQUFvRFFnQUUzTEw1RldmVFgvL3BJaXNEL0xneFVIT2lxdlFTSUVWTgpGekloOTdLZXBlWk1iZVZsUGd1akZ4Yk5MN2x1ZVhRQnBpUWUzNmZLN0xSbXZNNHdEaWZFTkE9PQotLS0tLUVORCBQVUJMSUMgS0VZLS0tLS0="
}

Sign previously issued customer challenge

post

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

Authorizations
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

Example: eip155:1:0xab16a96D359eC26a11e2C2b3d8f8B8942d5Bfcdb
challengestring Β· byteRequired

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

Example: LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUZZd0VBWUhLb1pJemowQ0FRWUZLNEVFQUFvRFFnQUUzTEw1RldmVFgvL3BJaXNEL0xneFVIT2lxdlFTSUVWTgpGekloOTdLZXBlWk1iZVZsUGd1akZ4Yk5MN2x1ZVhRQnBpUWUzNmZLN0xSbXZNNHdEaWZFTkE9PQotLS0tLUVORCBQVUJMSUMgS0VZLS0tLS0=
signaturestring Β· byteRequired

Base64 encoded signature

Example: IfvwaW1eCqLvQaK0/7YjvK8HBGHWHPclHHQWH4L+w6Q3CFS8CjSzq0h8G8AhzTGMc0xRrik3TyvrDm8t1JtL9Bw=
Responses
204
Successful operation
400
Invalid request
401
Not authorised
404
Customer not found
409
Challenge already signed
500
Internal error
post
POST /v1/customers/{customerId}/challenge/sign HTTP/1.1
Host: api.offblocks.xyz
Authorization: Bearer JWT
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="
}

No content