NAV Navbar
AnchorUSD API

Introduction

Welcome to the AnchorUSD API documentation.

The AnchorUSD API allows developers to integrate the AnchorUSD deposit flow into their apps.

This enables wallet providers to allow their users to deposit AnchorUSD without having to leave the wallet.

The flow is divided into 3 steps:

  1. Create deposit intent
  2. Open iframe to allow interactive AnchorUSD onboarding
  3. Handle success and failure postMessage from iframe

The iframe deposit flow allows you to initiate a deposit, specifying the user’s email address and the Stellar account address that funds should be deposited to.

First, you make a request to our deposit endpoint. We will return a URL that you should load in an iframe.

Then, you load this URL in an iframe, and listen for our success message that we’ll send using Window.postMessage.

Between steps (1) and (2) you can optionally use the submit KYC information endpoint to submit textual KYC information collected from your user. This essentially allows your user to skip a step of the interactive onboarding flow, if you are already collecting their textual KYC information.

AnchorUSD Asset Definitions

Please refer to these asset definitions when adding trustlines to AnchorUSD. Learn more about trustlines.

Testnet

Mainnet

Verify this with the AnchorUSD stellar.toml.

Authentication


curl 'https://sandbox-api.anchorusd.com/transfer/deposit' \
  -u sk_8pbjDbBDKcrsbMrrWthkwK:

The AnchorUSD API is designed for compliance with Stellar's SEP-0006 protocol, enabling wallets to interact with anchors. As such, the fundamental Create Deposit Intent and Create Withdraw Intent API methods are permissionless — they do not require an API key.

Nevertheless, we introduce an optional API key system that allows platforms to attribute the requests that they are making to their own users. Providing the API key allows for additional capabilities and visibility into the lifecycle of the transactions that you have created for your users.

The authentication system is HTTP Basic Auth, with an API key as the user field (password component left blank.)

To request an API key for your platform, contact us at support+api@anchorusd.com.

Create Deposit Intent

curl 'https://sandbox-api.anchorusd.com/transfer/deposit?account=GBP3XOFYC6TWUIRZAB7MB6MTUZBCREAYB4E7XKE3OWDP75VU5JB74ZF6&asset_code=USD&email_address=j%40anchorusd.com

This endpoint creates the initial intent to deposit AnchorUSD at an address.

HTTP Request

GET https://sandbox-api.anchorusd.com/transfer/deposit

Query Parameters

Parameter Type Description
asset_code string The code of the asset the user is wanting to deposit. Currently, this should always be set to USD
account string The stellar account ID of the user that wants to deposit. This is where the asset token will be sent. This account must have a trustline established with AnchorUSD. Refer to AnchorUSD Asset Definitions
memo_type string (optional) type of memo that anchor should attach to the Stellar payment transaction, one of text, id or hash
memo string (optional) value of memo to attach to transaction, for hash this should be base64-encoded.
email_address string Email address of depositor. If desired, an anchor can use this to send email updates to the user about the deposit.

HTTP Response

{
  "type": "interactive_customer_info_needed",
  "url": "https://sandbox-portal.anchorusd.com/onboarding?account=GBP3XOFYC6TWUIRZAB7MB6MTUZBCREAYB4E7XKE3OWDP75VU5JB74ZF6&identifier=0c4bb73672aa4f8ee0826387a4fd1e30",
  "identifer": "0c4bb73672aa4f8ee0826387a4fd1e30"
}

AnchorUSD will respond with status code 403 Forbidden, to indicate that interactive onboarding is required before the user can make a deposit. The response format is as follows:

Name Type Description
type string Always set to interactive_customer_info_needed
url string URL hosted by AnchorUSD. You should show this URL to the user either as a popup or an iframe. Please note that this URL is one-time use only. If you need to reattempt a deposit, begin with a new request to create deposit intent.
identifier string Identifier of the deposit intent. This can be passed to the submit KYC information endpoint, instead of immediately opening the url in an iframe.

Submit KYC Information

This endpoint is used to submit textual KYC information to AnchorUSD on behalf of your user. Please note that it takes a single-use identifier rather than an API key. The reason for this is that it is intended, and expected, to be executed clientside. In other words -- use this endpoint if you are collecting textual KYC information for your users that matches the information that AnchorUSD needs to collect. And if you are doing so, submit that information to AnchorUSD using this endpoint directly at the time of collection.

HTTP Request

POST https://sandbox-api.anchorusd.com/api/register

curl -X POST https://sandbox-api.anchorusd.com/api/register \
  -d identifier=e0be7328623201ad561c1fc0153b4644 \
  -d name="Test User" \
  -d birthday[month]=6 \
  -d birthday[day]=8  \
  -d birthday[year]=1993 \
  -d "tax-country"=US \
  -d "tax-id-number"=111111111 \
  -d "address[street-1]"="123 4 Street" \
  -d address[city]="Anytown" \
  -d "address[postal-code]"=94107 \
  -d address[region]=CA \
  -d address[country]=US \
  -d "primary-phone-number"=+14151111111 \
  -d gender=male

POST Parameters

Parameter Type Description
identifier string The identifier string returned in the call to create deposit intent
name string The full name (first and last) of the user.
birthday dictionary Birthday provided via subkeys month, day, and year
tax-country string Country of the user, for tax purposes. 2-letter ISO country code, all caps
tax-id-number string Tax ID of the user, eg SSN
address dictionary User address provided via subkeys street-1, street-2 (optional), city, postal-code, region, and country (2-letter ISO country code)
primary-phone-number string User phone number. Include + and country code.
gender string User gender (male, female, or other)

HTTP Response

{
  "result": "success",
  "url": "https://sandbox-portal.anchorusd.com/onboarding?account=GB2YROSEX7LHPDPMYAAX4UJY4TKWWF4W7JAJ46NBKCXHYZTWVLHBEWXI&identifier=e0be7328623201ad561c1fc0153b4644&nonce=d7dc78a570ba4f0da81334cfe0c04329"
}
Name Type Description
result string One of success or additional_fields_needed
url string URL hosted by AnchorUSD. You should show this URL to the user either as a popup or an iframe. Please note that this URL is one-time use only. If you need to reattempt a deposit, begin with a new request to create deposit intent.
account_id string (optional) A unique identifier for the user account that has been created. This is only returned when an API key is used for the request. Learn more about authentication.

Upon successful KYC submission, AnchorUSD will respond will the staus code 200 and a response that includes result=success.

If not all KYC fields were provided, or certain fields failed basic validation checks, AnchorUSD will respond with result=additional_fields_needed.

In either case, the next step is to send the user to the url provided. You should send the user through the rest of interactive onboarding flow by opening the returned url in an iframe. This will enable them either to enter the fields that are needed, or continue immediately to the purchase screen. Refer to the instructions in open iframe onboarding flow.

Retrieve KYC Status

You can retrieve the review status for KYC information that you have submitted via the API. This will indicate if the KYC information is under review, or if additional information has been requested.

Authentication required.

GET https://sandbox-api.anchorusd.com/api/accounts/:account_id/kyc

HTTP Response

{
  "account_id": "account_foo",
  "kyc_status": "passed",
}
Name Type Description
account_id string The user's account id (identical to the parameter provided in the URL path)
kyc_status string One of passed, additional_fields_needed, automatic_review_pending, identity_document_upload_needed, identity_document_in_review, tax_id_upload_needed, tax_id_in_review, address_verification_upload_needed, address_verification_in_review, failed, unsubmitted

Open iframe Onboarding Flow

<!-- Example HTML to open onboarding flow in iframe -->
<html>

<body style="background-color: #FFCB3D;">

<!-- Note: Be sure to add &callback=postMessage to the url returned by Create Deposit Intent -->
<iframe \
  style="margin-left: 200px; margin-top: 200px; width: 840px; height: 640px;" \
  src="https://sandbox-portal.anchorusd.com/ onboarding?account=GBP3XOFYC6TWUIRZAB7MB6MTUZBCREAYB4E7XKE3OWDP75VU5JB74ZF6&identifier=0c4bb73672aa4f8ee0826387a4fd1e30&callback=postMessage" \
></iframe>

<div id="message">
</div>

<script type="text/javascript">
  window.addEventListener("message", receiveMessage, false);

  function receiveMessage(event)
  {
    if (event.origin !== "https://sandbox-portal.anchorusd.com")
      return;

    var data = JSON.parse(event.data);
    if (data.status == 'success') {
      document.getElementById("message").innerHTML = "Success!";
    }
  }
</script>
</body>
</html>

After receiving a URL from create deposit intent, you should open this URL in either a popup or an iframe. A full HTML example is on the right.

HTTP Request

GET https://sandbox-portal.anchorusd.com?account=foo&identifier=bar&callback=postMessage

Append &callback=postMessage to the URL returned by create deposit intent to signify that you would like success and failure communicated to you via postMessage.

Handle Result

{
  "type": "customer_info_status",
  "status": "success"
}

When the user completes the onboarding flow and initiates a deposit, AnchorUSD will signal the result via postMessage.

Name Type Description
type string Always set to customer_info_status
status string One of success, pending, denied

Status interpretations:

AnchorUSD Issuance

Once the user's bank transfer has completed successfully, AnchorUSD will transfer the deposit amount directly to the Stellar account specified in the initial create deposit intent request.

On mainnet, this will take approximately 2-3 business days.

On testnet, AnchorUSD will immediately transfer the funds to the account specified.

Withdrawals

You can also utilize the AnchorUSD API to integrate AnchorUSD withdrawal functionality into your app. The basic withdraw flow matches the deposit flow:

  1. Create withdraw intent
  2. Open iframe to alllow interactive AnchorUSD onboarding
  3. Handle success and failure postMessage from iframe

However, whereas the deposit flow ends with your user initiating a bank transfer and you receiving a success message, the result of the interactive withdrawal flow is you receiving instructions for where to send AnchorUSD tokens no the Stellar blockchain to complete the withdrawal. These instructions are desribed in detail below.

Create Withdraw Intent

curl 'https://sandbox-api.anchorusd.com/transfer/withdraw?type=bank_account&asset_code=USD&email_address=j%40anchorusd.com

This endpoint creates the initial intent to withdraw AnchorUSD from the blockchain to a bank account.

HTTP Request

GET https://sandbox-api.anchorusd.com/transfer/withdraw

Query Parameters

Parameter Type Description
type string The type of withdraw, meaning the way in which funds should be withdrawn. Currently, this should always be set to bank_account
asset_code string The code of the asset the user is wanting to withdraw. Currently, this should always be set to USD
account string The stellar account ID of the user will send blockchain funds from. The system will expect that funds to satisfy the withdrawal will be sent from this address.
amount float (optional) The amount that the user intends to withdraw. If this is not specified, the user will be able to select the amount prior to confirming their withdrawal intent.
email_address string The user's email address. AnchorUSD may send email to this address with transaction confirmations or other updates.

HTTP Response

{
  "type": "interactive_customer_info_needed",
  "url": "https://sandbox.anchorusd.com/onboarding?account=GBP3XOFYC6TWUIRZAB7MB6MTUZBCREAYB4E7XKE3OWDP75VU5JB74ZF6&type=withdraw&&identifier=0c4bb73672aa4f8ee0826387a4fd1e30",
  "identifer": "0c4bb73672aa4f8ee0826387a4fd1e30"
}

AnchorUSD will respond with status code 403 Forbidden, to indicate that interactive onboarding is required before the user can make a withdraw. The response format is as follows:

Name Type Description
type string Always set to interactive_customer_info_needed
url string URL hosted by AnchorUSD. You should show this URL to the user either as a popup or an iframe. Please note that this URL is one-time use only. If you need to reattempt a withdraw, begin with a new request to create withdraw intent.
identifier string Identifier of the withdraw intent. This can be passed to the submit KYC information endpoint, instead of immediately opening the url in an iframe.

Handle Result

{
  "type": "withdraw",
  "status": "success",
  "account_id": "GAZBLEL2ZUFTDDFTQ3O4BZDH6EB2RXB4ATXHCXJLNHS23JRR444OJTLO",
  "memo_type": "hash",
  "memo": "133651cb5bfd079687998bc81e862502688e0bd92e2820b0e19a2c448bf7bbee",
  "dest": "******1234",
  "dest_extra": "Example Savings Bank",
  "amount": 1000,
  "amount_in": 1000,
  "amount_out": 980,
  "amount_fee": 20,
}

The user flow for submitting KYC information follows the same path as it does for deposits -- you can submit the KYC information via the API and ultimately open the interactive onboardindg flow for the user. The difference in the flow comes once user onboarding has been completed and the user has confirmed their intent to withdraw.

When the user completes the onboarding flow and confirms the intent to withdraw AnchorUSD will provide you with instructions on where to send on-chain funds in order to go through with the withdraw.

Name Type Description
type string Always set to withdraw
status string One of success, pending, denied. If pending or denied, the user will need to follow up in order to receive instructions to finalize the deposit. If success, the fields below will be inclulded.
account_id string The Stellar network address to send funds to.
memo_type string The type of memo to attach to the Stellar transaction when funds are sent. Will currently always be hash.
memo string a 32 byte hash, formatted in base 64
dest string The last 4 digits of the bank account that the user will be withdrawing funds to.
dest_extra string The name of the bank that the user will be withdrawing funds to.
amount float The withdraw amount that the user has selected.
amount_in float The total amount of funds that the user is instructed to send. Will currently always be equal to amount
amount_out float The net amount of funds that the user can expect to see sent to their bank account.
amount_fee float The fee charged by AnchorUSD for the service.

Some notes on how to interpret the fields returned: