This document explains how to initiate and track token transfers within the OmniSafe API.

1

Initiating a Token Transfer

To initiate a token transfer between two wallets, use the POST /v1/transfers endpoint.

  • Endpoint: POST /v1/transfers - Transfer API Reference
  • Summary: Transfers a token between two wallets.
  • Description: This endpoint initiates a token transfer on the blockchain between two wallets. The request body specifies the sender’s wallet address, the recipient’s wallet address, the token to be transferred, and the quantity. Upon successful processing, a transfer ID (idInClient) is returned. If the idInClient already exists, a 409 error will be returned.

Request Body:

The request body should conform to the BlockchainTransactionDto schema (defined in the OpenAPI specification). It typically includes:

  • fromWalletAddress: The address of the sender’s wallet.
  • toWalletAddress: The address of the recipient’s wallet.
  • tokenId: The ID of the token to be transferred.
  • quantity: The amount of the token to transfer.
  • idInClient: A unique identifier for this transfer, provided by the client. This is crucial for tracking the transfer status.

Response:

  • 201 Created: Returns the idInClient (string) of the created transfer transaction.
  • 409 Conflict: Returned if the idInClient already exists.

Important Considerations:

  • idInClient Uniqueness: The idInClient must be unique for each transfer you initiate. Reusing an idInClient will result in a 409 error.
  • Asynchronous Processing: Transfer initiation creates a transaction on the blockchain. Confirmation may take some time depending on network conditions.
2

Getting Transfer Status

To retrieve the status of a previously initiated token transfer, use the GET /v1/transfers/{id-in-client} endpoint.

  • Endpoint: GET /v1/transfers/{id-in-client} - Get Transfer Status API Reference
  • Summary: Gets the status of a previously initiated token transfer.
  • Description: Retrieves the status of a previously initiated token transfer on the blockchain. You’ll need the idInClient that was returned by the POST /v1/transfers endpoint.

Parameters:

  • idInClient (path parameter): The client-provided ID of the transfer you want to track.

Response:

  • 200 OK: Returns an array of TransferStatusDto objects, containing the current status of the transfer. The TransferStatusDto typically includes:
  • transactionHash: The blockchain transaction hash (if the transfer has been confirmed).
  • status: The current status of the transfer (e.g., “PENDING”, “DONE”, “FAILED”).
  • errorMessage: Any error messages encountered during the transfer process.
  • 404 Not Found: Returned if a transfer with the specified idInClient is not found.

Transfer Status Values:

The status field in the TransferStatusDto response can have the following values (examples, your values may differ):

  • PENDING: The transfer has been initiated but has not yet been confirmed on the blockchain.
  • DONE: The transfer has been successfully confirmed on the blockchain.
  • FAILED: The transfer failed due to an error. Check the errorMessage field for details.