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:
- Create deposit intent
- Open iframe to allow interactive AnchorUSD onboarding
- 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
- Asset Code:
USD
- Asset Issuer:
GCKFBEIYV2U22IO2BJ4KVJOIP7XPWQGQFKKWXR6DOSJBV7STMAQSMTGG
Mainnet
- Asset Code:
USD
- Asset Issuer:
GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX
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:
success
the deposit was successfulpending
the user exited prior to completing the onboarding processdenied
the user submitted KYC information but did not immediately pass, either due to requiring manual review or due to more information being needed. AnchorUSD will email the user to notify them of required information, or of eventual success.
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:
- Create withdraw intent
- Open iframe to alllow interactive AnchorUSD onboarding
- 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:
account_id
,memo
, andmemo_type
define where the user should send funds in order to complete the withdrawal. If your application is a wallet application, the expectation is that you will facilitate the user transferring funds without the need to copy and paste these fields.amount
is the amount of AnchorUSD funds to send.dest
,dest_extra
,amount_out
, andamount_fee
are supplemental fields that can be used to display a confirmation screen to your user so that they are able to double-check the quantity of funds that they are sending, and what their total expect net bank account transfer will be, prior to confirming and initiating the transfer.