Arkiv app integration

Choose the signing boundary before adding an endpoint. Arkiv access keys authenticate RPC access; they do not authorize your application's users or pay the signer's gas.

Server APIs

• Keep signing keys and X-API-KEY access headers server-side. Use the consumer's secret store; never ask for private keys in chat or put them in public environment variables or browser bundles.
• Authenticate the session, authorize the specific operation and check CSRF, apply an attempt limit, bound and validate input, then apply a separate write limit. Invalid input consumes only the attempt budget. Test denial paths against the writer.
• A shared signer owns its new entities. Derive user identity from the verified session and enforce user access in the backend. A user_id attribute alone cannot enforce it on-chain. Choose a shared signer, separate server signers or a browser EOA deliberately.
• Require a stable Idempotency-Key and a durable operation registry before writing. Bind each user's operation ID to normalized input, chain and signer; changed input conflicts. Serialize all writers sharing that signer across processes and persist intent/nonce/signed bytes/hash before broadcasting. Return known key/hash and phase on uncertain outcomes; a timeout never authorizes a second create. See arkiv-write-safety for reconciliation.
• Give read proxies an allowlist of filters, page-size and total-page limits, response-size bounds and their own rate limits. Do not expose arbitrary credentialed RPC methods.
• For fresh Next.js RPC reads, use client cacheTime: 0 and http(url, { fetchOptions: { cache: "no-store" } }); explicitly bypass cached heads for snapshot/expiration checks. Inspect route, application, service-worker and CDN caches too; RPC transport options cannot clear those caches.
• Return a narrow DTO with bigint block fields converted to decimal strings. Validate entity.toJson() before copying fields, then attach arkivEntityKey from the actual entity key.

Read server-boundary.md for the authorization seam and payload/DTO example. Supply real session, authorization, CSRF, rate limits and the required durable writer; a callback that directly creates on every retry violates its contract.

For provider HTTP 401/403/429, preserve the actual status, provider code and safe diagnostic fields; never return an empty successful query. Check the access key's network, monthly cost-unit quota and IP/Origin allowlists in the access-key guide. An Origin header can be forged outside a browser and is not application authentication. Respect Retry-After and provider cost/reset headers when supplied, stop retry storms, and keep credentialed URLs/headers out of client errors. App session failures and app rate limits are separate from provider denials.

Browser wallets and caches