📒Blockchain Updates

Our API includes various endpoints that involve on-chain activities and updates, such as ownership verification and smart contract deployment. In order to provide smooth experience and maximum level of security, we employ cryptographic challenges and signatures tailored to each supported blockchain.

Account Creation

To create a new account for the customer and set it up for fund transfers with OffBlocks, we need to deploy a smart-contract account to the respective blockchain. The customer remains the ultimate owner of this account, and to manage funds for off-chain transactions on the user's behalf, we need them to sign a session key issued in the form of a cryptographic challenge. Similar to other endpoints, the challenge returned by the endpoint is a Base64-encoded string.

Create new customer account

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

POSThttps://api.offblocks.xyz/v1/customers/{customerId}/accounts

Authorization

bearerAuth

Path parameters

customerId*string (uuid)

Unique customer ID

Header parameters

Body

application/json

type*enum

Type of the account

card_account

currencies*array of string

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

Response

201400401404500

Successful operation

Body

application/json

id*string (uuid)

Unique account ID

customerId*string (uuid)

Unique customer ID

chainIdstring

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

status*enum

Account status

initiatingpendingactiveinactiveclosedfailed

type*enum

Type of the account

card_account

currenciesarray of string

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

createdAt*string (date-time)

Date this account was created (ISO-8601)

updatedAt*string (date-time)

Date this account was updated (ISO-8601)

challenge*string (byte)

Base64 encoded message provided by this API for owner to sign

Request

JavaScriptCurlPythonHTTP

const response = await fetch('https://api.offblocks.xyz/v1/customers/{customerId}/accounts', {
    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({
      "type": "card_account",
      "currencies": [
        null
      ]
    }),
});
const data = await response.json();

Response

201

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "customerId": "123e4567-e89b-12d3-a456-426614174000",
  "chainId": "eip155:1:0xab16a96D359eC26a11e2C2b3d8f8B8942d5Bfcdb",
  "status": "initiating",
  "type": "card_account",
  "currencies": [
    "text"
  ],
  "createdAt": "2025-02-05T04:04:19.551Z",
  "updatedAt": "2025-02-05T04:04:19.551Z",
  "challenge": "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUZZd0VBWUhLb1pJemowQ0FRWUZLNEVFQUFvRFFnQUUzTEw1RldmVFgvL3BJaXNEL0xneFVIT2lxdlFTSUVWTgpGekloOTdLZXBlWk1iZVZsUGd1akZ4Yk5MN2x1ZVhRQnBpUWUzNmZLN0xSbXZNNHdEaWZFTkE9PQotLS0tLUVORCBQVUJMSUMgS0VZLS0tLS0="
}

To submit a signed challenge, please use the corresponding endpoint.

Sign previously issued account challenge

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

POSThttps://api.offblocks.xyz/v1/accounts/{accountId}/challenge/sign

Authorization

bearerAuth

Path parameters

accountId*string (uuid)

Unique account ID

Header parameters

Body

application/json

ownerId*string

Unique signer account ID in a form of a valid on-chain address

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

JavaScriptCurlPythonHTTP

const response = await fetch('https://api.offblocks.xyz/v1/accounts/{accountId}/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": "eip155:1:0xab16a96D359eC26a11e2C2b3d8f8B8942d5Bfcdb",
      "challenge": "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUZZd0VBWUhLb1pJemowQ0FRWUZLNEVFQUFvRFFnQUUzTEw1RldmVFgvL3BJaXNEL0xneFVIT2lxdlFTSUVWTgpGekloOTdLZXBlWk1iZVZsUGd1akZ4Yk5MN2x1ZVhRQnBpUWUzNmZLN0xSbXZNNHdEaWZFTkE9PQotLS0tLUVORCBQVUJMSUMgS0VZLS0tLS0=",
      "signature": "IfvwaW1eCqLvQaK0/7YjvK8HBGHWHPclHHQWH4L+w6Q3CFS8CjSzq0h8G8AhzTGMc0xRrik3TyvrDm8t1JtL9Bw="
    }),
});
const data = await response.json();

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

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

GEThttps://api.offblocks.xyz/v1/accounts/{accountId}/challenge

Authorization

bearerAuth

Path parameters

accountId*string (uuid)

Unique account 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

JavaScriptCurlPythonHTTP

const response = await fetch('https://api.offblocks.xyz/v1/accounts/{accountId}/challenge', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer JWT",
      "Signature": "text",
      "Signature-Input": "text"
    },
});
const data = await response.json();

Response

200

{
  "challenge": "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUZZd0VBWUhLb1pJemowQ0FRWUZLNEVFQUFvRFFnQUUzTEw1RldmVFgvL3BJaXNEL0xneFVIT2lxdlFTSUVWTgpGekloOTdLZXBlWk1iZVZsUGd1akZ4Yk5MN2x1ZVhRQnBpUWUzNmZLN0xSbXZNNHdEaWZFTkE9PQotLS0tLUVORCBQVUJMSUMgS0VZLS0tLS0="
}