> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anchorage.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting started

> Set up a key, sign your first v4 request, and learn the conventions every Crypto as a Service endpoint shares.

This page covers the conventions that every v4 endpoint shares: authentication, request signing, idempotency, batch results, pagination, and errors. Read it once, then go to the guide for the flow you're building.

## Base URLs

| Environment | Base URL |
| :- | :- |
| Sandbox | `https://api.anchorage-staging.com/v4` |

The v4 API runs in the sandbox today. Production access comes with general availability, with its own keys, accounts, and asset list.

## Set up access

**1. Create a permission group and an API key**

v4 keys are created the same way as any other Anchorage Digital API key: an administrator creates a [permission group](https://docs.anchorage.com/knowledge-base/platform/developers/permission-groups.md), then an [API key](https://docs.anchorage.com/knowledge-base/platform/developers/api-keys.md) from your own Ed25519 public key. Each v4 endpoint names the permission it needs in its reference page, for example **Manage Accounts** or **Initiate withdrawals**.

**2. Send a read request**

Every request carries your access key in the `Api-Access-Key` header. The asset list needs no other permission, so it's a good first call.

```bash theme={null}
curl --request GET \
     --url https://api.anchorage-staging.com/v4/asset-types \
     --header 'Api-Access-Key: {API Key}'
```

**3. Sign a write request**

Every `POST`, `PATCH`, and `DELETE` also carries `Api-Signature`, `Api-Timestamp`, and `Idempotency-Key`. See [Request headers](#request-headers) below.

## Request headers

| Header | When | Value |
| :- | :- | :- |
| `Api-Access-Key` | Every request | Your API access key |
| `Api-Timestamp` | Every write | Current time as Unix epoch seconds |
| `Api-Signature` | Every write | Hex-encoded Ed25519 signature of `timestamp + uppercase(method) + request path + request body` |
| `Idempotency-Key` | Every write | A key you generate, unique per logical request |
| `If-Match` | `PATCH /accounts/{accountId}` only, optional | The `ETag` from an earlier read of the account |

The signature input is the same as for the v2 API, so an existing signer works unchanged: the request path includes the `/v4` prefix and any query string, and the body is the exact bytes you send, with no extra whitespace. The timestamp must be within one minute of server time. See [Signing requests](https://docs.anchorage.com/knowledge-base/platform/developers/request-signing.md) for working code in several languages.

### Idempotency

Reusing an `Idempotency-Key` returns the original result instead of repeating the action. That makes writes safe to retry after a timeout: send the same request with the same key, and you get back what the first attempt produced. Reusing a key with a different body returns `409 Conflict`.

Generate a fresh key for every logical action, including when you repeat an action on purpose, such as re-enrolling an account you unenrolled a minute ago.

### Concurrency on account updates

`GET /accounts/{accountId}` returns an `ETag` header. Pass it back as `If-Match` on `PATCH /accounts/{accountId}` to make the update conditional: if the account changed since you read it, the update is refused with `409 Conflict`. `If-Match` is optional. Leave it out to update unconditionally. Account updates are under construction today, so the header has no effect yet.

## Batch operations

Creating accounts, compliance profiles, customers, and withdrawals, and freezing, unfreezing, and closing accounts, all take a list and return a result per item. The response is `202 Accepted` (or `200` for freeze, unfreeze, and close) with one entry per item you sent, in the same order.

```json theme={null}
{
  "data": [
    { "index": 0, "id": "cb80459c-a930-444e-8f17-69ba9d0e122f", "status": "SUCCESS" },
    { "index": 1, "status": "ERROR", "error": "parent account not found" }
  ]
}
```

Each item succeeds or fails on its own. Check every entry: a `200` or `202` tells you the batch was processed, not that every item worked. Use `index` to match results to the items you sent, and treat only the `id` of a `SUCCESS` entry as created.

## Pagination

List endpoints accept `limit` (page size, 1 to 1,000, default 100) and `after` (a cursor). Each page returns `page.endCursor`. Pass it as `after` to fetch the next page. A `null` cursor means you have everything.

```bash theme={null}
curl --request GET \
     --url 'https://api.anchorage-staging.com/v4/accounts?limit=100&after=eyJvZmZzZXQiOjEwMH0' \
     --header 'Api-Access-Key: {API Key}' \
     --header 'accept: application/json'
```

> [!NOTE]
>
> The policy engine endpoints (`/policies`, `/approvers/*`, `/endorsements/*`) use the same `limit` and `after` parameters. A few older examples elsewhere use `first` for the page size. `limit` is correct.

## Errors

Every error response carries a JSON body with a human-readable `message`:

```json theme={null}
{
  "message": "Missing required field 'quantity'."
}
```

| Status | Meaning |
| :- | :- |
| `400` | The request failed validation, or broke a business rule. Trading rejections use the form `<rejectCode>: <detail>`. |
| `401` | The access key is missing or invalid |
| `403` | The key lacks the permission the endpoint names, or a policy denied the change |
| `404` | The resource doesn't exist in your organization |
| `409` | A conflict: a reused idempotency key with a different body, a stale `If-Match`, a duplicate `externalId`, or a state that doesn't allow the action |
| `422` | The request is valid but can't be applied, for example interest enrollment when interest isn't enabled for your organization |
| `429` | Rate limited. Back off and retry. |

When you report a problem to Anchorage Digital, include the `X-Anchorage-Trace-Id` response header. It lets us find your exact request.

## Notifications

Webhooks for the v4 API are coming soon. Until then, poll the read endpoints: an account until it reads `OPEN`, an order until it reaches a final status, a withdrawal until `COMPLETE`, and a deposit attribution until `ATTRIBUTED`. Each guide names the endpoint to poll.

## Decimal values

Every quantity, price, and rate is a decimal encoded as a string, such as `"0.25"` or `"15000.00"`. Send strings, not JSON numbers. Strings avoid the precision loss that floating-point numbers introduce on large or fractional amounts.

## Asset types

`GET /asset-types` lists the assets your organization can hold, with their name, decimal precision, and network. The list is authoritative: use it to decide which assets you can send `assetType` values for, rather than a list on a docs page.

```json theme={null}
{
  "data": [
    { "name": "Bitcoin", "decimals": 8, "network": "BTC", "support": ["CUSTODY"] }
  ]
}
```

The sandbox list holds testnet assets, so the codes differ from the production codes. At the time of writing they're `BTC_S` for Bitcoin Signet, `ETHHOODI` for Ethereum Hoodi, `USDANCHOODI` for USDC on Hoodi, and `USD_R` for USD. Trust the list the API returns over any docs page. Trading symbols are the exception: orders use the standard pair names, such as `BTC-USD`, in the sandbox too. To get sandbox access, contact your Anchorage Digital representative.

## Next steps

> [card] [Accounts](https://docs.anchorage.com/knowledge-base/platform/developers/caas/caas-accounts.md)
>
> Choose a structure, then open and manage accounts.

> [card] [Policies and approvals](https://docs.anchorage.com/knowledge-base/platform/developers/caas/caas-policies.md)
>
> Register approval keys and write the policies that govern changes.

> [card] [Trusted destinations](https://docs.anchorage.com/knowledge-base/platform/developers/caas/caas-trusted-destinations.md)
>
> Register where funds can be sent before you withdraw.

> [card] [Withdrawals](https://docs.anchorage.com/knowledge-base/platform/developers/caas/caas-withdrawals.md)
>
> Move funds out to a destination or another account.


## Related topics

- [Getting started](https://docs.anchorage.com/knowledge-base/platform/users/getting-started.md)
- [How it works](https://docs.anchorage.com/knowledge-base/porto/getting-started/how-it-works.md)
- [Atlas network](https://docs.anchorage.com/knowledge-base/porto/atlas.md)
- [Overview](https://docs.anchorage.com/knowledge-base/porto/developers/staking/staking-overview.md)
