6️⃣Account Creation

This step assumes you have successfully created a new customer record and verified it using Customer Creationand Customer Verification steps of the guide

Now that you have created and verified a first customer record, you are able to onboard the customer on OffBlocks accounts. To do so, you need to use /customers/{customerId}/account POST request.

Create new customer account

post

https://api.offblocks.xyz/v1https://api.sandbox.offblocks.xyz/v1

/customers/{customerId}/accounts

Creates new account for the customer and generates a challenge to be signed in order to create a related blockchain account

Authorizations

bearerAuth

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

application/json

typestring · enumRequired

Type of the account

Possible values:

currenciesstring[]Required

Currencies of the account, at least one is required (ISO-4217)

Responses

201

Successful operation

application/json

400

Invalid request

401

Not authorised

404

Customer not found

500

Internal error

post

/customers/{customerId}/accounts

HTTPcURLJavaScriptPython

POST /v1/customers/{customerId}/accounts 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: 45

{
  "type": "card_account",
  "currencies": [
    "text"
  ]
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "customerId": "123e4567-e89b-12d3-a456-426614174000",
  "chainId": "eip155:1:0xab16a96D359eC26a11e2C2b3d8f8B8942d5Bfcdb",
  "status": "initiating",
  "type": "card_account",
  "currencies": [
    "text"
  ],
  "createdAt": "2026-03-02T16:38:16.501Z",
  "updatedAt": "2026-03-02T16:38:16.501Z",
  "challenge": "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUZZd0VBWUhLb1pJemowQ0FRWUZLNEVFQUFvRFFnQUUzTEw1RldmVFgvL3BJaXNEL0xneFVIT2lxdlFTSUVWTgpGekloOTdLZXBlWk1iZVZsUGd1akZ4Yk5MN2x1ZVhRQnBpUWUzNmZLN0xSbXZNNHdEaWZFTkE9PQotLS0tLUVORCBQVUJMSUMgS0VZLS0tLS0="
}

Let's say we want to open a new card account (the only option for the time being) that's using Euro as a base currency (we don't support multi-currency accounts just yet):

{
  "type": "CARD_ACCOUNT",
  "currencies": [
    "EUR"
  ]
}

If everything was successful, you will receive a response with status 201 (Created) which looks similar to the following:

{
    "challenge": "NWRmMzU5ZjAtZDI5OS00MGExLTgwMjMtMTdjNzdhNTAxNDRj",
    "createdAt": "2024-01-12T15:07:17.358440283Z",
    "currencies": [
        "EUR"
    ],
    "customerId": "04c5851c-4386-5bd9-9f89-08312f8aee3a",
    "id": "ae61c362-4136-49af-8e01-544457fe265b",
    "status": "initiating",
    "type": "card_account",
    "updatedAt": "2024-01-12T15:07:17.358440283Z"
}

If everything went well, you will receive an account challenge to sign as a base64 encoded string. This is required to proceed to deployment stage. Signatures are not currently verified in our Sandbox environment, however they are still required to be submitted.

In order to submit a signed challenge, use a POST request to /accounts/{accountId}/challenge/sign endpoint.

Sign previously issued account challenge

post

https://api.offblocks.xyz/v1https://api.sandbox.offblocks.xyz/v1

/accounts/{accountId}/challenge/sign

Signs previously issued challenge to sign account creation or deletion transaction on-chain

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

accountIdstring · uuidRequired

Unique account ID

Header parameters

SignaturestringRequired

HTTP message signature

Signature-InputstringRequired

HTTP message signature input

Idempotency-Keystring · uuidRequired

Idempotency key (UUID)

Content-DigeststringRequired

Content digest

Body

application/json

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

Account not found

409

Challenge already signed

500

Internal error

post

/accounts/{accountId}/challenge/sign

HTTPcURLJavaScriptPython

POST /v1/accounts/{accountId}/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="
}

No content

{
  "ownerId": "eip155:280:0x43158f45b5EbD7b1179130131DF00393928C2691",
  "challenge": "NWRmMzU5ZjAtZDI5OS00MGExLTgwMjMtMTdjNzdhNTAxNDRj",
  "signature": "c2lnbmF0dXJl"
}

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.

Retrieve account challenge

get

https://api.offblocks.xyz/v1https://api.sandbox.offblocks.xyz/v1

/accounts/{accountId}/challenge

Retrieves challenge to sign account creation or deletion transaction on-chain. This operation invalidates any previously issued challenges for the account

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

accountIdstring · uuidRequired

Unique account ID

Header parameters

SignaturestringRequired

HTTP message signature

Signature-InputstringRequired

HTTP message signature input

Responses

200

Successful operation

application/json

Cryptographic challenge generated to be signed by owner's EOA private key according to chain-specific algorithm. Challenge is used for verifying ownership of the account and signing on-chain transactions such as creating a new account, authorising a recurring payment or setting up spending limits

challengestring · byteRequired

Base64 encoded message provided by this API for owner to sign

Example: LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUZZd0VBWUhLb1pJemowQ0FRWUZLNEVFQUFvRFFnQUUzTEw1RldmVFgvL3BJaXNEL0xneFVIT2lxdlFTSUVWTgpGekloOTdLZXBlWk1iZVZsUGd1akZ4Yk5MN2x1ZVhRQnBpUWUzNmZLN0xSbXZNNHdEaWZFTkE9PQotLS0tLUVORCBQVUJMSUMgS0VZLS0tLS0=

400

Invalid request

401

Not authorised

404

Account not found

500

Internal error

get

/accounts/{accountId}/challenge

HTTPcURLJavaScriptPython

GET /v1/accounts/{accountId}/challenge HTTP/1.1
Host: api.offblocks.xyz
Authorization: Bearer YOUR_SECRET_TOKEN
Signature: text
Signature-Input: text
Accept: */*

{
  "challenge": "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUZZd0VBWUhLb1pJemowQ0FRWUZLNEVFQUFvRFFnQUUzTEw1RldmVFgvL3BJaXNEL0xneFVIT2lxdlFTSUVWTgpGekloOTdLZXBlWk1iZVZsUGd1akZ4Yk5MN2x1ZVhRQnBpUWUzNmZLN0xSbXZNNHdEaWZFTkE9PQotLS0tLUVORCBQVUJMSUMgS0VZLS0tLS0="
}

Once the challenge has been successfully signed, we will proceed to deployment stage. The account will be automatically deployed and activated, which you can verify by making a GET request to /accounts/{accountId}.

Retrieve account

get

https://api.offblocks.xyz/v1https://api.sandbox.offblocks.xyz/v1

/accounts/{accountId}

Retrieves account's details

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

accountIdstring · uuidRequired

Unique account ID

Header parameters

SignaturestringRequired

HTTP message signature

Signature-InputstringRequired

HTTP message signature input

Responses

200

Successful operation

application/json

idstring · uuidRequired

Unique account ID

customerIdstring · uuidRequired

Unique customer ID

chainIdstringOptional

Unique account ID in a form of a valid on-chain address. This would normally correspond to account's SCA address

Example: eip155:1:0xab16a96D359eC26a11e2C2b3d8f8B8942d5Bfcdb

statusstring · enumRequired

Account status

Possible values:

typestring · enumRequired

Type of the account

Possible values:

currenciesstring[]Optional

Currencies of the account, at least one is required (ISO-4217)

createdAtstring · date-timeRequired

Date this account was created (ISO-8601)

updatedAtstring · date-timeRequired

Date this account was updated (ISO-8601)

400

Invalid request

401

Not authorised

404

Account not found

500

Internal error

get

/accounts/{accountId}

HTTPcURLJavaScriptPython

GET /v1/accounts/{accountId} HTTP/1.1
Host: api.offblocks.xyz
Authorization: Bearer YOUR_SECRET_TOKEN
Signature: text
Signature-Input: text
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "customerId": "123e4567-e89b-12d3-a456-426614174000",
  "chainId": "eip155:1:0xab16a96D359eC26a11e2C2b3d8f8B8942d5Bfcdb",
  "status": "initiating",
  "type": "card_account",
  "currencies": [
    "text"
  ],
  "createdAt": "2026-03-02T16:38:16.501Z",
  "updatedAt": "2026-03-02T16:38:16.501Z"
}

{
    "chainId": "eip155:280:0x18102C007e4B4FBED74105E8D1e4FF4545Dbed8f",
    "createdAt": "2024-01-12T15:07:17.35844Z",
    "currencies": [
        "EUR"
    ],
    "customerId": "04c5851c-4386-5bd9-9f89-08312f8aee3a",
    "id": "ae61c362-4136-49af-8e01-544457fe265b",
    "status": "active",
    "type": "card_account",
    "updatedAt": "2024-01-12T15:09:31.118452Z"
}

From there we can proceed to issuing cards for the account.