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

# API Fundamentals

> Base URL, shared request conventions, example format, and a production checklist for the PrimeVault API.

PrimeVault's external API is an organization-scoped JSON API. The rules below apply to every endpoint unless an endpoint page says otherwise. Request and response shapes match the current `@primevault/js-api-sdk`.

## Base URL

```text theme={null}
https://api.primevault.com
```

All paths are relative to this URL. Requests and responses are JSON unless noted.

## Start here

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api-basics/authentication">
    Credentials, request signing, headers, key safety, and auth troubleshooting.
  </Card>

  <Card title="Filtering and Pagination" icon="filter" href="/api-basics/filtering-and-pagination">
    List filters, `limit`, cursor pagination, and SDK iteration.
  </Card>

  <Card title="Status Codes" icon="signal" href="/api-basics/status-codes">
    HTTP status classes, SDK error types, and retry guidance.
  </Card>

  <Card title="Custom Error Codes" icon="triangle-exclamation" href="/api-basics/custom-error-codes">
    Error envelope, handling order, and endpoint-specific codes.
  </Card>
</CardGroup>

## Endpoint reference

<CardGroup cols={2}>
  <Card title="Endpoints" icon="code" href="https://docs.primevault.com/endpoints">
    Operations for assets and chains, vaults, transactions, contacts, and bank accounts.
  </Card>

  <Card title="Data Models" icon="database" href="/api-basics/data-models">
    Shared request and response objects.
  </Card>
</CardGroup>

Each operation lists its SDK method, REST path, parameters, request/response JSON, and validation or lifecycle notes.

## Shared request conventions

| Convention | Rule |
| :- | :- |
| Property names | camelCase. SDK `chain` parameters map to `blockChain` where the REST API expects it. |
| IDs | Opaque strings. Don't infer resource type, organization, or permissions from their format. |
| Amounts | Decimal strings such as `"12.50"`. **Never JSON numbers** — floats lose precision. |
| Optional fields | Omit if unused. Marked `?` in TypeScript types. |
| Organization scope | Set by the API user. Never use resource IDs from another organization. |
| Sub-orgs | Send `subOrgId` only where the request type defines it. On a party it identifies that party; at the top level it scopes the record. |
| Timestamps | ISO 8601, UTC, unless noted. |
| Unknown fields | Don't rely on undocumented response fields. Tolerate new ones without changing your requests. |

## JSON example convention

* **POST and PUT** examples show the actual request body.
* **GET** examples show path and query parameters as JSON for documentation only; they're encoded in the URL, not sent as a body.
* **Responses** are representative and may omit optional fields.

## Integration checklist

Complete these before going to production.

<Steps>
  <Step title="Create a dedicated API user">
    Keep its private key out of source control. See [Setting Up an API User](/getting-started/setting-up-api-user).
  </Step>

  <Step title="Verify authentication">
    Call a read-only endpoint with the official SDK.
  </Step>

  <Step title="Implement pagination">
    Use cursor traversal on every list endpoint you consume.
  </Step>

  <Step title="Handle errors in order">
    Typed HTTP errors first, then custom error codes.
  </Step>

  <Step title="Retry safely">
    When retrying a timed-out transaction creation, reuse a stable client reference where supported.
  </Step>

  <Step title="Log without secrets">
    Log request context, HTTP status, and error code — never credentials or sensitive payloads.
  </Step>
</Steps>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.