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

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*CustomerId (string (uuid))

ID of customer

Header parameters

Body

application/json

type*AccountType (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*CustomerId (string (uuid))

customerId*CustomerId (string (uuid))

chainIdBlockchainAccountId (string)

Universal unique on-chain identifier of the account following CAIP-10 specification

status*AccountStatus (enum)

Account status

initiatingpendingactiveinactiveclosedfailed

type*AccountType (enum)

Type of the account

card_account

currenciesarray of string

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

createdAt*DateTime (string (date-time))

ISO-8601 timestamp

updatedAt*DateTime (string (date-time))

ISO-8601 timestamp

challenge*string (byte)

Base64 encoded message provided by this API for owner to sign

Request

JavaScriptCurlPython

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": [
        "text"
      ]
    }),
});
const data = await response.json();

Response

201

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "customerId": "123e4567-e89b-12d3-a456-426614174000",
  "chainId": "text",
  "status": "initiating",
  "type": "card_account",
  "currencies": [
    "text"
  ],
  "createdAt": "2024-11-21T06:37:22.321Z",
  "updatedAt": "2024-11-21T06:37:22.321Z",
  "challenge": "Ynl0ZXM="
}

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

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*CustomerId (string (uuid))

ID of account to be challenged

Header parameters

Body

application/json

ownerId*BlockchainAccountId (string)

Universal unique on-chain identifier of the account following CAIP-10 specification

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

JavaScriptCurlPython

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": "text",
      "challenge": "Ynl0ZXM=",
      "signature": "Ynl0ZXM="
    }),
});
const data = await response.json();

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

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*AccountId (any)

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

JavaScriptCurlPython

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": "Ynl0ZXM="
}

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

Retrieves account's details

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

Authorization

bearerAuth

Path parameters

accountId*AccountId (any)

Unique account ID

Header parameters

Response

200400401404500

Successful operation

Body

application/json

id*CustomerId (string (uuid))

customerId*CustomerId (string (uuid))

chainIdBlockchainAccountId (string)

Universal unique on-chain identifier of the account following CAIP-10 specification

status*AccountStatus (enum)

Account status

initiatingpendingactiveinactiveclosedfailed

type*AccountType (enum)

Type of the account

card_account

currenciesarray of string

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

createdAt*DateTime (string (date-time))

ISO-8601 timestamp

updatedAt*DateTime (string (date-time))

ISO-8601 timestamp

Request

JavaScriptCurlPython

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

Response

200

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "customerId": "123e4567-e89b-12d3-a456-426614174000",
  "chainId": "text",
  "status": "initiating",
  "type": "card_account",
  "currencies": [
    "text"
  ],
  "createdAt": "2024-11-21T06:37:22.321Z",
  "updatedAt": "2024-11-21T06:37:22.321Z"
}

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