SEP 6
INTRODUCTION
SEP 6 provides a standard way for anchors and wallets to interact on behalf of its users. For non-interactive components, SEP 6 provides a way for users to interact with anchors programmatically. The interactive components of SEP 6 are deprecated in favor of SEP 24.
SEP 6 provides a standard protocol for the following
(i) Deposit external assets to anchor.
(ii) Withdraw assets from an anchor
(iii)Display deposit & withdrawal fee structure for an anchor to the user
(iv)Handle anchor KYC needs, including transmitting KYC information about the user to the anchor via SEP-12
(v)Check the status of current deposits or withdrawals.
(vi)Show a history of deposits and withdrawals.
Prerequisites
(i) An anchor must define the location of their TRANSFER_SERVER in their stellar.toml. This helps a wallet find the anchor's server.
(ii) Anchors and clients may support SEP-10 web authentication to enable authenticated withdrawals and deposits.
API ENDPOINTS
To support this protocol an anchor acts as a server and implements some API endpoints, while a wallet acts as a client that consumes these API endpoints. The following are the endpoints that should be implemented by an anchor for SEP 6.
(i) GET /deposit :- REQUIRED
(ii) GET /withdraw :- REQUIRED
(iii) GET /info :- REQUIRED
(iv) GET /fee :- OPTIONAL (only needed for complex fee structures)
(v) GET /transactions :- REQUIRED
(vi) GET /transaction :- REQUIRED
AUTHENTICATION
An anchor may support SEP 10 for authentication so that users can be verified while depositing or withdrawing assets and even for checking transaction history.
For implementing authentication, the anchor should
(i) set the authentication_required field at their info endpoint.
(ii) Provide JWT obtained from SEP 10 to all endpoints.
Interactive authentication
For interactive flow, authentication can be achieved by including JWT obtained from SEP 10 as a header like this
Authorization: Bearer <JWT>
Non-interactive authentication
For non-interactive authentication, JWT should be passed as a query parameter like this
?jwt=<token>
CORS Permissions
To allow clients from any site to access the endpoint, we have to enable CORS by enabling the following header in the server.
Access-Control-Allow-Origin: *
HTTPS only
Since this protocol involves deposit and withdrawal of assets that have value, hence https is required for all the endpoints.
ENDPOINTS DESCRIPTION
(i) DEPOSIT
The deposit endpoint helps the user initiate the deposit process to an anchor. The user deposits some currency be it fiat or crypto and the anchor provides the equivalent stellar assets to the user. This endpoint provides all the info that a user may need regarding the deposit.
Deposit Request
GET TRANSFER_SERVER/deposit
Request parameters
The request parameters contain a lot of fields that you can check out HERE.
Deposit Response
For the JSON response, you can check out the official documentation HERE.
SPECIAL CASES
There are some special cases that anchors must handle for the deposit endpoint.
(i) The stellar account does not exist:- If the stellar accountId provided by the user does not exist, then anchor may create the account on the user's behalf with enough balance to issue trustline for deposit asset. If the anchor doesn't support this create new account operation, then the response should be 404 BAD REQUEST error.
(ii)The stellar account doesn't trust the asset:- Since the secret for stellar address remains with the user, an anchor cannot issue trustline on behalf of the user. That's why anchor should do the following
When the anchor gets the deposit request, it starts listening to check if the user address has enough balance to issue a trustline for the deposited asset. If not, then anchor listens for the account to get a minimum balance to issue a trustline for the deposit address.
Once the user gets enough balance, then the anchor listens to keep checking if the user has issued a trustline for the given asset. If yes, then anchor sends the asset to the user, otherwise, the anchor keeps listening for users to issue trust lines.
(ii) WITHDRAW
Withdraw operation allows to user to send the asset it holds back to the anchor to redeem the asset it originally deposited.
The withdraw endpoint gives the user all the info it needs to perform the withdrawal operation.
REQUEST
GET TRANSFER_SERVER/to withdraw
REQUEST PARAMETERS
There is a whole list of request parameters to get info about withdrawing assets from an anchor. You can check out the whole list of request parameters in the official docs HERE.
WITHDRAW RESPONSE
You can check out the whole list of parameters that the anchor returns in the official docs HERE.
HANDLING SPECIAL CASES FOR DEPOSIT AND WITHDRAW
There are some scenarios shared by deposit and withdraw endpoints which must be handled by the anchor to implement SEP 6.
(a) Customer Information needed (Non-interactive flow)
If the anchor needs more info about the user and that can info can be received non-interactively via SEP-12. Then the response code should be 403 Forbidden.
The response should contain the following fields
|
|
|
|
|
|
|
|
|
|
|
|
The field names specified in fields must be drawn from the list defined in SEP-9.
Sample response in this scenario may look like this
{
"type": "non_interactive_customer_info_needed",
"fields" : ["family_name", "given_name", "address", "tax_id"]
}
The user can retry deposit or withdrawal transactions once the given info is given to the anchor.
(b) CUSTOMER INFORMATION STATUS
In this scenario, the customer has given the requisite information to the anchor but the request is still being processed or may be rejected due to some reason. In this case, if the user tries to do a deposit or withdraw, then they should get response code 403 Forbidden.
The JSON response object, in this case, would contain the following fields
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Sample response in this scenario would look something like this.
{
"type": "customer_info_status",
"status": "denied",
"more_info_url": "https://api.example.com/kycstatus?account=GACW7NONV43MZIFHCOKCQJAKSJSISSICFVUJ2C6EZIW5773OU3HD64VI"
}
(c) Authentication Required
If the endpoint is accessed without any authentication i.e a jwt, then the status code to be returned is 403 Forbidden.
{
"type": "authentication_required"
}
(d) Error
In any other scenario, the response would be deemed as an error, the returned JSON response should contain the reason for the error in a human-readable format.
{
"error": "This anchor doesn't support the given currency: BTC"
}
(iii) INFO
This endpoint allows an anchor to convey info about the TRANSFER_SERVER to wallets and clients.
REQUEST PARAMETERS
This endpoint takes a single parameter called "lang" which tells the anchor which language the response data should be in. It is optional and defaults to en (English).
RESPONSE
The response for info endpoint looks like THIS.
The response for info endpoint contains two objects, deposit and withdraw. Both these objects contain a list of assets that anchor supports and their deposit and withdraw details respectively.
Each asset in deposit object contains the following details
- enabled:- This is set to true if anchor supports deposit for this asset.
- authentication_required:- This is set to true if the client needs authentication to access the endpoints. False if not specified.
- min_amount:-(OPTIONAL) min amount of asset to be deposit/withdraw. No limit if not specified.
- max_amount:-(OPTIONAL) max amount of asset to be deposited/withdrawn. No limit if not specified.
- fee_fixed:- (OPTIONAL) fixed fee that would be deduced while deposit/withdraws in terms of the deposited/withdrawn asset.
- fee_percent:- (OPTIONAL) fee as a percentage of deposited/withdrawn amount that would be deducted from the amount deposited/withdrawn.
- fields:- It's a JSON object that contains the following fields.
- description:- A description of field to show to user.
- optional:- true if a field is optional. Defaults to false.
- choices:- a list of possible values for the field.
The response for the info endpoint should also contain if they support other endpoints like fees, transactions and transactions. For each of these endpoints, the response should specify the following.
- enabled:- true if the endpoint is available on the anchor.
- authentication_required:- true if the client must be authenticated before accessing the endpoint.
(iv) FEE
This endpoint allows an anchor to show the details about the fee that would be deducted during the deposit and withdrawal. The fee may be fixed in terms of the deposited or withdrawn asset or the fee may be a percentage fee which is directly proportional to the amount of asset deposited or withdrawn asset.
NOTE:- If the details for this endpoint can be shown in the info endpoint, then anchor should not implement this endpoint at all.
REQUEST
GET TRANSFER_SERVER/fee
REQUEST PARAMETERS
The request parameters that this endpoint takes can be found HERE.
RESPONSE
The response for this endpoint looks like HERE.
(v) TRANSACTION HISTORY
This endpoint shows a history of transactions that the user has performed with the anchor in the past. These transactions are either deposit or withdrawal.
REQUEST
GET TRANSFER_SERVER/transactions
REQUEST PARAMETERS
The parameter list for this endpoint can be found HERE.
RESPONSE
The JSON response to this endpoint looks something like THIS.
(vi) SINGLE TRANSACTION
This endpoint gives the user details about a specific transaction.
REQUEST
GET TRANSFER_SERVER/transaction
REQUEST PARAMETERS
The parameters list for this endpoint can be found HERE.
RESPONSE
The JSON response for this endpoint looks something like THIS.
CONCLUSION
In this blog, we learned about SEP 6, the endpoint it supports, the standard request and response for these endpoints.
REFERENCE
The official documentation for SEP 6 can be found HERE.
For implementing authentication, you can refer to SEP 10 documentation HERE.
November 21, 2024 at 10:54 am
Your comment is awaiting moderation.