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