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. API Integration

Idempotency

PreviousRequest SignaturesNextBlockchain Identifiers

Last updated 1 year ago

The OffBlocks API supports API idempotency. This allows safe request retries (during the validity time window of the key) while only performing the requested action once.

For example, if there is a temporary connection issue, a request to create an account could be safely retried several times without creating multiple accounts.

Always use a different idempotency key for different requests

You must use different idempotency keys for different requests. Reusing the same idempotency key will cause the subsequent requests to not be executed. Reuse of an idempotency key with a different payload, while the key is still valid, results in an error.

Enabling Idempotency

To use idempotency, where required (this includes all modifying requests such as POST, PUT, PATCH and DELETE), add the Idempotency-Key header as shown in the following example endpoint. We expect a key in a format of UUID to be provided. This is automatically generated and populated for relevant requests in our Postman collection.

Scope and Validity

Each idempotency key has a duration of 1 hour.

During the validity period, you can only send the same payload with the same idempotency key. If you do this, you receive an identical response.

If the payload is different, but the idempotency key is the same, you receive an error. The error is likely 422 or 409, explained below.

Error Handling

These are some of the common errors associated with idempotency:

Error code
Error type
Detail
Solution

400

BadRequest

Invalid request signature.

Include the Idempotency-Key header when making requests to endpoints where idempotency is mandatory.

409

Idempotency-Key Concurrency Conflict

The Idempotency-Key value is being used for a concurrent request.

You submit a new request with a different idempotency key. This error occurs because another request with the same idempotency key is in flight. If you wait until the request is no longer in flight and make the same request with the same idempotency key, you receive an identical response.

422

Idempotency-Key Reuse

The Idempotency-Key value has already been used for a different request.

Make your request with a new idempotency key. Technically, you could also wait for the validity period of the idempotency key to end after 1 hours.

βš™οΈ
πŸ†”
  • Enabling Idempotency
  • POSTCreate new customer
  • Scope and Validity
  • Error Handling

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:49:00.315Z",
  "updatedAt": "2025-05-09T06:49:00.315Z",
  "challenge": "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUZZd0VBWUhLb1pJemowQ0FRWUZLNEVFQUFvRFFnQUUzTEw1RldmVFgvL3BJaXNEL0xneFVIT2lxdlFTSUVWTgpGekloOTdLZXBlWk1iZVZsUGd1akZ4Yk5MN2x1ZVhRQnBpUWUzNmZLN0xSbXZNNHdEaWZFTkE9PQotLS0tLUVORCBQVUJMSUMgS0VZLS0tLS0="
}