API documentation Stellar Anchors provides support for token deposits and withdrawals on the Stellar network.

Summary

• 1. Overview
• 2. Domains
  • 2.1. Public Network
  • 2.2. Test Network
• 3. SEPs
• 4. Integrating
  • 4.1. Fetch stellar.toml
  • 4.2. Get auth token
  • 4.3. Trustline
  • 4.4. Deposit
  • 4.5. Withdrawal
  • 4.6. Direct transfer (Anchor-Anchor)
• 5. Wallet CLI

1. Overview

As a Stellar Anchor, you can deposit and withdraw tokens using your Stellar account.
The protocols which define how to deposit and withdraw are called SEPs.
Each SEP can be found in the Stellar git repository. The main focus of this document is to guide Wallets on how to manage deposits and withdrawals using a Stellar Anchor. The relevant SEPs for this document are listed below.

Here are a few links to help you get started:

• Stellar Introduction
• Stellar Tools
• Stellar Awesome Links
• Javascript Tutorial
• SEP-24 Instructions for Wallets
• SEP-6 Instructions for Wallets
• Anchor Validator

Overview of the steps to do a deposit or withdrawal using our Anchor:

• Fetch stellar.toml
  • The Wallet fetches the Anchor's stellar.toml file, which contains information about currencies and URLs required by the SEPs
• Create trustlines to the Anchor
  • In order to hold assets issued, the Wallet must create a trustline to the asset on each of its Stellar accounts. Otherwise the accounts won't be able to receive the deposits.
• Create a deposit or withdrawal transaction using SEP-6 or SEP-24
  • The main difference between SEP-6 and SEP-24 is that SEP-6 requires the Wallet to collect all required fields from the user and submit them non-interactively to the Anchor. In SEP-24, the Anchor interactively collects all the information it needs from the user.
  • It's up to the Wallet to decide to use SEP-6 or SEP-24 to manage transactions.

Stellar has two networks: testnet and public.
Our Anchor operates on both networks, and the domains are listed below.
More details on how to integrate with our Anchor are found below.

2. Domains

2.1. Public Network

Domain:
https://clpx.finance

Assets:

• CLPX (fiat)

fiat assets represent currencies in the real world (EUR, USD) and can be deposited/withdrawn directly to bank accounts.

2.2. Test Network

Domain:
https://ktest.clpx.finance (tbd)

Assets:

• PURPLE

3. SEPs

• SEP-1: fully compliant
• SEP-2: not supported
• SEP-6: fully compliant, requires account to be already verified, see notes below
• SEP-10: fully compliant
• SEP-12: not supported
• SEP-24: fully compliant
• SEP-31: being tested on testnet

4. Integrating

4.1. Fetch stellar.toml

stellar.toml provides these variables, which are required for SEP-10, SEP-6 and SEP-24 respectively:

• WEB_AUTH_ENDPOINT
• TRANSFER_SERVER
• TRANSFER_SERVER_SEP0024

Python example on how to fetch the testnet stellar.toml:

import requests
import toml

stellar_toml = toml.loads(requests.get('https://clpx.finance/.well-known/stellar.toml').text)

4.2. Get auth token

SEP-10 provides a mechanism to prove ownership of a Stellar account and obtain a reusable JWT token which carries the ownership information.
The token is required in many transaction endpoints (SEP-24, SEP-6, etc) and allow the Wallet to deposit and withdrawal funds on the account through a Stellar Anchor. The token is usually valid for 1 day after it's generated, and can be used in all HTTP requests while it's valid.

Python example (based on Django Polaris code) on how to get a new JWT token:

from stellar_sdk.keypair import Keypair
from stellar_sdk.transaction_envelope import TransactionEnvelope
from stellar_sdk.network import Network

secret_key = 'SBYWIVPVH5PQPB...'

auth_url = stellar_toml['WEB_AUTH_ENDPOINT']

# get challenge transaction and sign it
client_signing_key = Keypair.from_secret(secret_key)
response = requests.get(f'{auth_url}?account={client_signing_key.public_key}')
content = json.loads(response.content)
envelope_xdr = content['transaction']
envelope_object = TransactionEnvelope.from_xdr(
    envelope_xdr, network_passphrase=Network.TESTNET_NETWORK_PASSPHRASE
)
envelope_object.sign(client_signing_key)
client_signed_envelope_xdr = envelope_object.to_xdr()

# submit the signed transaction to prove ownership of the account
response = requests.post(
    auth_url,
    json={"transaction": client_signed_envelope_xdr},
)
content = json.loads(response.content)

sep10_token = content['token']

4.3. Trustline

To deposit assets into a Stellar account, the account must first trust the asset.
A trustline operation is required only once and the trust will last forever on the account unless removed.
Python example on how to trust an Anchor asset:

from stellar_sdk.server import Server
from stellar_sdk.transaction_builder import TransactionBuilder

secret_key = 'SBYWIVPV...'
horizon_testnet = 'https://horizon-testnet.stellar.org/'
asset_info = stellar_toml['CURRENCIES'][0]

server = Server(horizon_url=horizon_testnet)
keypair = Keypair.from_secret(secret_key)
account = server.load_account(keypair.public_key)
builder = TransactionBuilder(source_account=account,
        network_passphrase=Network.TESTNET_NETWORK_PASSPHRASE)
builder.append_change_trust_op(asset_code=asset_info['code'],
        asset_issuer=asset_info['issuer'])
envelope = builder.build()
envelope.sign(keypair)
response = server.submit_transaction(envelope)
assert response['successful']

4.4. Deposit

Deposits are a way for users to deposit real world currencies (ex: USD, EUR) into their Stellar account (usually managed by a Wallet).
For example, a user can have EUR on a bank account outside Stellar, and deposit that as CLPX into a Stellar account.
To deposit assets, the Wallet must create deposit transactions on our Anchor.
To create transactions, there are two options:

• SEP-6
  • Non-interactive - Wallet must provide all required information through HTTP requests
  • Does not require opening any external web page
  • See example below
• SEP-24
  • Interactive - all information needed from the user is collected by the Anchor using web pages
  • Requires opening a popup window or iframe pointing to an URL provided by the Anchor
  • See example below

SEP-6 Deposit Python example:

def sep6_deposit():
    data = {
        'asset_code': 'PURPLE',
        'account': 'GC75JLZ6...',

        # these fields are specific for this Anchor,
        #  they're specified on the SEP-6 /info endpoint
        'type': 'sepa',  # SEPA transfer deposit
        'first_name': 'John',
        'last_name': 'Doe',
        'email_address': '[email protected]',
        'amount': '11.0',
    }
    headers = {
        'Authorization': 'Bearer ' + sep10_token
    }
    url = stellar_toml['TRANSFER_SERVER'] + '/deposit'
    response = requests.post(url, data=data, headers=headers).json()
    return render_sep6_instructions(response)  # display instructions to user

SEP-24 Deposit Python example:

def sep24_deposit():
    data = {
        'asset_code': 'PURPLE',
        'account': 'GC75JLZ6...',
    }
    headers = {
        'Authorization': 'Bearer ' + sep10_token
    }
    url = stellar_toml['TRANSFER_SERVER_SEP0024'] + '/transactions/deposit/interactive'
    response = requests.post(url, data=data, headers=headers).json()
    return render_sep24_interactive(response['url'])  # popup window on the client

4.5. Withdrawal

Withdrawals are a way for users to obtain assets from their Stellar account as real world currencies (ex: USD, EUR).
For example, a user can have token balance in a Stellar account and withdraw that as fiat, receiving the fiat on a bank account outside Stellar.
To withdraw assets, the Wallet must create withdrawal transactions on the Anchor.
To create transactions, there are two options:

• SEP-6
  • Non-interactive - Wallet must provide all required information through API requests
  • Does not require opening any external web page
  • See example below
• SEP-24
  • Interactive - all information needed from the user is collected by the Anchor using web pages
  • Requires opening a popup window or iframe pointing to an URL provided by the Anchor
  • See example below

SEP-6 Withdrawal Python example:

def sep6_withdrawal():
    data = {
        'asset_code': 'PURPLE',

        # these fields,
        #  they're specified on the SEP-6 /info endpoint
        'amount': '12.5',
        'type': 'cash',
        'dest_country': 'uk',
        'benef_first_name': 'John',
        'benef_last_name': 'Doe',
        'benef_email': '[email protected]',
    }
    headers = {
        'Authorization': 'Bearer ' + sep10_token
    }
    url = stellar_toml['TRANSFER_SERVER'] + '/withdraw'
    response = requests.post(url, data=data, headers=headers).json()
    return render_sep6_instructions(response)  # display instructions to user

SEP-24 Withdrawal Python example:

def sep24_withdrawal():
    data = {
        'asset_code': 'PURPLE',
    }
    headers = {
        'Authorization': 'Bearer ' + sep10_token
    }
    url = stellar_toml['TRANSFER_SERVER_SEP0024'] + '/transactions/withdraw/interactive'
    response = requests.post(url, data=data, headers=headers).json()
    return render_sep24_interactive(response['url'])  # popup window on the client

4.6. Direct transfer (Anchor-Anchor)

A direct transfer is a Stellar payment made between two Anchor accounts.
For example, let's say Anchor A is a bank and Anchor B is another bank.
A person who has a bank account in Anchor A wants to send a money transfer to another person who has a bank account in Anchor B.
Normally, this can be accomplished via standard bank transfers like SEPA, Wire, etc.
With SEP-31, Anchor A can send a Stellar payment to Anchor B instead of a bank transfer, this allows the anchors to take advantage of the speed of Stellar payments and avoid the burocracy of standard bank transfers (which can take days to take place).

• SEP-31
  • Used for anchor-anchor direct transfers
  • Non-interactive - Anchor must provide all required information through API requests
  • Does not require opening any external web page
  • See example below

SEP-31 Python example:

def sep31_create_transaction():
    payload = {
        "amount": 15.0,
        "asset_code": "PURPLE",
        "fields": {
            "transaction": {
                "remitter_email": "[email protected]",
                "remitter_first_name": "John",
                "remitter_last_name": "Doe",
                "remitter_phone_number": "+4906921999510",
                "beneficiary_email": "[email protected]",
                "beneficiary_first_name": "Ana",
                "beneficiary_last_name": "Doe",
                "beneficiary_bank_iban": "GB02 REVO 0099 7040 2170 16",
                "beneficiary_bank_bic": "CHASUS33",
                "beneficiary_phone_number": "+4906921999510"
            }
        }
    }
    headers = {
        'Authorization': 'Bearer ' + sep10_token
    }
    url = stellar_toml['TRANSFER_SERVER_SEP0031'] + '/transactions'
    response = requests.post(url, json=payload, headers=headers).json()
    return response

5. Wallet CLI

This repository contains a CLI Stellar wallet implementation for demonstration purposes.

5.1. Requirements

• Python3.6+
• pip3

5.2. Dependencies

cd wallet-cli
python3 -m pip install virtualenv
python3 -m virtualenv .venv
pip install -r requirements.txt

5.3. Running

Activate virtualenv (required only once for a terminal session):

source .venv/bin/activate

Create the database:

python cli.py database create

Get started by looking at the options:

python cli.py --help

Examples:

# SEP-1
python cli.py sep1 fetch_stellar_toml

# Trust
python cli.py trust change_trust

# SEP-10
python cli.py sep10 auth

# See SEP-24 options
python cli.py sep24 --help