API Fundamentals

primevault's external api is an organization scoped json api this reference is aligned with the current @primevault/js api sdk request serializers and exported response types base url https //api primevault com all endpoint paths are relative to this url requests and responses use json unless an endpoint explicitly says otherwise start here these global rules apply to every endpoint unless an endpoint page documents a narrower requirement guide use it for authentication https //docs primevault com/authentication api credentials, request signing, required headers, credential safety, and authorization troubleshooting filtering and pagination https //docs primevault com/filtering and pagination list filters, limit , cursor traversal, deterministic pagination, and sdk iteration patterns status codes https //docs primevault com/status codes http success and failure classes, javascript sdk error types, and retry guidance custom error codes https //docs primevault com/custom error codes primevault's machine readable error envelope, handling order, and endpoint specific code references endpoint reference section contents endpoints https //docs primevault com/endpoints callable api operations grouped by asset and chain, vault, transaction, and address book data models https //docs primevault com/data models shared request and response objects referenced by endpoint pages each operation includes its sdk method, rest path, parameters, request json where applicable, response json, and important validation or lifecycle notes shared request conventions convention rule property names rest payloads use camelcase sdk method parameters named chain are serialized as blockchain where the rest api expects that field ids treat ids as opaque strings do not infer resource type, organization, or permissions from their format amounts send monetary and token amounts as decimal strings, for example "12 50" do not use floating point numbers optional fields omit fields you do not need a typescript ? marks an optional field organization scope the api user determines the organization never send or reuse a resource id from another organization sub organizations send suborgid only on request types that define it party level suborgid identifies that party; a top level suborgid scopes the containing record timestamps timestamps are iso 8601 strings in utc unless the endpoint says otherwise unknown fields do not depend on undocumented response fields clients should tolerate new response fields without changing request payloads json example convention post and put request examples show the actual rest request body get examples use a documentation only path and query object so every operation has a concrete json request representation; those objects are encoded into the url and are not sent as a body response examples are representative they include the stable fields needed to understand the contract and can omit optional fields that are not returned for every resource integration checklist create a dedicated api user and keep its private key outside source control initialize the official sdk and confirm authentication against a read only endpoint implement cursor traversal for every list endpoint you consume handle typed http errors first, then documented custom error codes use stable client references where available before retrying transaction creation after a timeout log request context, http status, and custom error code without logging credentials or sensitive payload data