Understanding token transfers within the OmniSafe API.
This document explains how to initiate and track token transfers within the OmniSafe API.
Initiating a Token Transfer
To initiate a token transfer between two wallets, use the POST /v1/transfers
endpoint.
POST /v1/transfers
- Transfer API ReferenceidInClient
) 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.Getting Transfer Status
To retrieve the status of a previously initiated token transfer, use the GET /v1/transfers/{id-in-client}
endpoint.
GET /v1/transfers/{id-in-client}
- Get Transfer Status API ReferenceidInClient
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.