| Read vault activity (READ) |
See an overview of your vault(s) and wallets. Read vault details, balances, asset types, transaction history and deposit addresses. |
| Create address (CREATE_DEPOSIT_ADDRESS) |
Receive deposits in the vault from external sources. Create and read deposit addresses. |
| Transfer funds (TRANSFER) |
This permission is configurable to enable an API key endowed with this permission to either 1) Transfer funds to any Anchorage Digital institutional account, including those outside of your organization or 2) Transfer funds to any blockchain address not custodied by Anchorage Digital that has gone through quorum approval. |
| Propose and accept settlements (PROPOSE_ACCEPT_SETTLEMENTS) |
This is an Atlas specific permission for initiating settlements. |
| Authorize settlements (AUTHORIZE_SETTLEMENTS) |
This is an Atlas specific permission for authorizing settlements after they've been proposed or accepted. |
There are also special vault permissions for enabled by Anchorage Digital on a per-organization basis:
Additionally, there are global permissions which apply to the entire organization:
| Initiate withdrawals (INITIATE_WITHDRAWAL) |
Initiate withdrawals to external destinations. All withdrawals require quorum approval through the Anchorage Digital mobile app. |
| Execute trades (TRADE) |
Request for quotes (RFQ) from the Anchorage Digital trading desk. Create and accept quotes. Read data of trades and settlements created by this key. |
| Read trade activity (READ_TRADE) |
Read trade activity and trade settlements data of your organization. |
| Read lending activity (LENDER_READ) |
Read lending activity of your organization. |
| Read facility data (FACILITY_ONLY) |
Read lending facility data. |
| Read deposit attribution activity (READ_DEPOSIT_ATTRIBUTION) |
Read deposit attribution activity of your organization. |
| Manage deposit attributions (DEPOSIT_ATTRIBUTION) |
Read deposit attribution activity of your organization. Perform deposit attributions. |
| Initiate Staking and Unstaking (STAKE) |
Initiate staking or unstaking operation. All operations require quorum approval through the Anchorage Digital mobile app. |
### Example Workflow - Allow transfers from specific vaults
To create an API key with the ability to transfer funds from an Anchorage Digital vaults or wallet, a permission group must first be created with the **Transfer funds** permission for the desired source vaults. Creating this permission group requires a quorum of approvals on the Anchorage Digital iOS app. Once the creation is confirmed, any number of API keys may be created with this permission group in the Anchorage Digital Web Dashboard under the API 2.0 section.
To add additional permissions to the API key, update the associated permission group through the Anchorage Digital Web Dashboard. To revoke any permissions, the individual API key may be revoked, or the permission group may be updated or deleted to remove Transfer access.
## API Keys
All API requests must be made over HTTPS and must include authentication using the following scheme.
### Generating an API Key
In order to make a valid API request, you must first create an API key. API keys can be created and managed in the Anchorage Digital Web Dashboard under the [API 2.0 tab](https://anchoragelogin.com/api). When you create an API key, there are 3 pieces of information you will need to remember:
- API access key
- Ed25519 public key (optional for read-only requests)
- Ed25519 private/signing key (optional for read-only requests)
You must generate an Ed25519 signing key pair and save the public portion in the Anchorage Digital Web Dashboard when creating the API access key. The signing key pair is used for added security with sensitive requests.
Please note, Anchorage Digital cannot recover your API access key or private signing key if you forget them. You may generate a new access key and signing key at any time if you lose access.
### API Key Permissions
Each API key is associated with a permission group. This permission group specifies the permitted actions for all associated API keys. Read more about permission groups [here](#section/Authentication-and-Security/Permission-Groups).
### Creating a request
All requests must include the `Api-Access-Key` header, which contains your API access key as a string.
Endpoints that require a signature must include the `Api-Signature` and `Api-Timestamp` headers. Read more about signatures [here](#section/Authentication-and-Security/Signatures).
All request bodies must be valid JSON and have the content type `application/json`.
## Request Signatures
Certain endpoints require an Ed25519 signature to be provided alongside the API key. These endpoints will specify the `Api-Signature` and `Api-Timestamp` headers as additional parameters.
Signatures are optional unless explicitly required, but are encouraged for all requests. If a signature is provided, it will be verified.
### Signing Keys
A signing key pair is generated by the user and the corresponding public key must be provided when creating an API key.
When creating an API key, you will be prompted to provide an Ed25519 public key. You must use the associated Ed25519 signing key (private key) when creating signatures for requests from this API key.
Please note that signing keys (Ed25519 private keys) should be stored securely by the user. The signing key should only be used to derive request signatures and should never be sent in a request. Anchorage Digital will never request you share your private key.
### Generating a Signing Key
The user must securely generate an Ed25519 key pair on their own hardware and retain both the public and private portions. The Anchorage Digital API accepts a 64-character (32 bytes) hex-encoded Ed25519 public key when creating an API access key.
#### Code sample (Python)
*Generate a new signing key pair*
```python
# https://pypi.org/project/PyNaCl/
import nacl
import nacl.signing
import secrets
seed = secrets.token_bytes(32)
# Generate a new random signing key
signing_key = nacl.signing.SigningKey(seed)
# Obtain the hex-encoded signing key
print('Signing key:')
print(signing_key.encode().hex())
# Obtain the hex-encoded verify key for the given signing key
# Use this in the Anchorage Digital Web Dashboard when creating an API key
print('Public key:')
print(signing_key.verify_key.encode().hex())
```
### Signing a Request
To sign a request, generate a request signature using the Ed25519 private (signing) key and provide it alongside the request in the `Api-Signature` header.
To create a request signature, first concatenate the `timestamp`, `method`, `request path`, and `body` into a string. Then, create a signature of this message using the Ed25519 private key and hex-encode the output. Use this value as the `Api-Signature` header and use the `timestamp` value as the `Api-Timestamp` header.
- The `method` is an uppercase HTTP method (ex. `GET`, `POST`, `DELETE`)
- The `request path` should contain all query parameters (ex. `/v2/transfers?foo=bar&baz=bang`)
- The `body` is a stringified HTTP request body
- The `body` should be omitted if the request does not contain a body (ex. a `GET` or `DELETE` request)
- The `timestamp` is the same as the `Api-Timestamp` header
- The `timestamp` is a number of seconds since the Unix Epoch in UTC, and must be within one minute of the API service's time when the request is received
### Reference signature
To verify your signature generation code is correct, generate a signature for the following request and timestamp using the provided signing key. If the generated signature matches the signature below, your signature generation code is correct.
| Timestamp |
1577880000 |
| HTTP Method (Uppercase) |
POST |
| HTTP Path + query |
/v2/transfers?foo=bar&baz=bang |
| HTTP Body |
{"source": {"id": "1c920f4241b78a1d483a29f3c24b6c4c", "type": "VAULT"}, "assetType": "ETH", "destination": {"id": "55e89d4a644d736b01533a2ea9b32a20", "type": "VAULT"}, "amount": "1000.00000000"} |
| Signing Key (Ed25519 Private Key Seed) |
0101010101010101010101010101010101010101010101010101010101010101 |
| Public Key |
8a88e3dd7409f195fd52db2d3cba5d72ca6709bf1d94121bf3748801b40f6f5c |
| Signature |
4bf42054bf7db1f8a2a2bc83d2a108502ee7a9d2ac7a2738adc2f932922446786fb9be1bd1eb475023296c6cba4ddbe28b04baca4b7521b1f1840a4ffd2b4d0d |
## Reference clients
### Python (with `requests` library)
*Authorize and sign requests*
```python
# https://pypi.org/project/PyNaCl/
from nacl import signing
import time
import requests
class AnchorageAuth(requests.auth.AuthBase):
ACCESS_KEY_HEADER = "Api-Access-Key"
SIGNATURE_HEADER = "Api-Signature"
TIMESTAMP_HEADER = "Api-Timestamp"
access_key: str
signing_key: signing.SigningKey
def __init__(self, access_key: str, signing_key_seed: bytes):
self.access_key = access_key
self.signing_key = signing.SigningKey(signing_key_seed)
def __call__(self, r: requests.PreparedRequest):
r.headers[self.ACCESS_KEY_HEADER] = self.access_key
timestamp = str(int(time.time()))
method = r.method.upper() if r.method else "GET"
body: bytes = bytes()
if r.body and isinstance(r.body, bytes):
body = r.body
elif r.body and isinstance(r.body, str):
body = bytearray(r.body, "utf-8")
message = b"".join(
[bytearray(timestamp, "utf-8"), bytearray(method, "utf-8"), bytearray(r.path_url, "utf-8"), body]
)
signature = self.signing_key.sign(message).signature.hex()
r.headers[self.SIGNATURE_HEADER] = signature
r.headers[self.TIMESTAMP_HEADER] = timestamp
return r
# load secrets
# Use the API key generated in the Anchorage Digital Web Dashboard
access_key = ...
# Use the Ed25519 signing private key
signing_key_str = ... # load the raw string
signing_key = bytes(bytearray.fromhex(signing_key_str))
data = {}
anchorage_auth = AnchorageAuth(access_key, signing_key)
r = requests.post("https://api.anchorage.com/v2/transfers", data=data, auth=anchorage_auth)
```
### Ruby - Reproduce reference signature
```ruby
require "ed25519"
require "net/http"
require "time"
def hex_to_bin(s)
[s].pack('H*')
end
def bin_to_hex(s)
s.unpack('H*').first
end
private_key_seed_hex = '0101010101010101010101010101010101010101010101010101010101010101'
public_key_hex = '8a88e3dd7409f195fd52db2d3cba5d72ca6709bf1d94121bf3748801b40f6f5c'
key_pair_hex = private_key_seed_hex + public_key_hex
key_pair = hex_to_bin(key_pair_hex)
signing_key = Ed25519::SigningKey.from_keypair(key_pair)
timestamp = '1577880000' # Time.now.to_i.to_s
req = Net::HTTP::Post.new('/v2/transfers?foo=bar&baz=bang')
req.body = '{"source": {"id": "1c920f4241b78a1d483a29f3c24b6c4c", "type": "VAULT"}, "assetType": "ETH", "destination": {"id": "55e89d4a644d736b01533a2ea9b32a20", "type": VAULT"}, "amount": "1000.00000000"}'
signature = signing_key.sign(timestamp + req.method + req.path + req.body)
req['Api-Access-Key'] = 'YOUR_ACCESS_KEY'
req['Api-Timestamp'] = timestamp
req['Api-Signature'] = bin_to_hex(signature)
puts bin_to_hex(signature)
```
# Errors
The Anchorage Digital API returns standard HTTP error codes for each API request.
| Response Code |
Description |
| 200 OK |
The request was successful. |
| 400 Bad Request |
The request was improperly formed and could not be understood by the server, often due to invalid syntax, insufficient funds, or a missing required parameter. |
| 401 Unauthorized |
The request was missing a valid API key. |
| 403 Forbidden |
The provided API key does not have permission to perform the requested action. |
| 404 Not Found |
The requested resource does not exist. |
| 409 Conflict |
The requested resource cannot proceed with the requested action because it is not in the required state. |
| 429 Too Many Requests |
Too many requests have been sent in a given amount of time. |
500 Internal Server Error
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout
|
Something went wrong on Anchorage’s side. We have been alerted and are working on it. |
In addition to returning HTTP error codes for failed requests, the Anchorage Digital API includes a readable error message describing what went wrong in the response body.