# Arctex Integration Guide Arctex One provides digital asset payment processing through the Arctex API. Use this guide with the [API reference](/) to integrate supported assets and blockchain networks, recover uncertain requests, and reconcile financial events. ## Implementation status and evidence The API is an **integration preview**, using draft contract v0.5.0 for `/v1`. All 17 HTTP operations and three webhook types are implemented. Recorded acceptance covers isolated HTTP, persistent financial history, credential and webhook-key rotation, and funded test-network bridge/payout recovery after restart. The Go integration kit has passed independent compilation, consumer tests and reproducible generation checks. These results establish tested implementation paths. Your application still needs its own integration acceptance, and production activation requires operational approval. No production API deployment or service-level agreement is claimed by this preview. Support is limited to enabled assets, configured routes and the capabilities of your installation. Public documentation is available at `https://docs.arctex.one`. The `api.arctex.one` name is reserved for the API; use the endpoint issued during onboarding rather than assuming production API availability. `https://api.arctex.invalid` in examples is a deliberately non-routable placeholder; it is not a sandbox address. ## Quickstart 1. Obtain your installation endpoint, bearer credential, permitted financial accounts, enabled assets and approved support channel during onboarding. 2. Read `/v1/assets` and `/v1/accounts`. Match the complete asset identity, including its network and token contract when applicable. 3. For incoming payments, create a receiving address and retain its reference, address, memo and your own customer mapping before presenting it to a customer. 4. For an outgoing transfer, request a quote. Retain its instructions, amounts, fees, expiry and your correlation before submitting that quote. 5. Persist each POST's original `Idempotency-Key` and request before sending. Recover uncertain results with the same identity and input. 6. Authenticate and durably store webhooks. Use recovery reads and committed financial effects to reconcile your application. For example, read the enabled asset catalog with your issued endpoint and credential substituted for these placeholders: ```sh curl --fail-with-body https://api.arctex.invalid/v1/assets \ -H 'Authorization: Bearer ' ``` After obtaining an executable quote, submit its retained reference: ```sh curl --fail-with-body https://api.arctex.invalid/v1/transfers \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: example-transfer-001' \ --data '{"quote_ref":"quote_example_01","client_reference":"order_1042"}' ``` The example key and references are illustrative. Assign and persist your own identity for each intended operation. Never replace it merely because a response is lost, a request times out or a dependency is unavailable. ## Authentication and account scope Send your bearer credential in the `Authorization` header. Credentials determine the tenant, initiating actor and permitted financial accounts. Account filters and resource references cannot grant additional access. Keep credentials and webhook keys in your approved secret-management system; do not log them or include them in client-side applications. Credential issuance, account provisioning, webhook subscriptions and exceptional recovery are handled through authorized administration. The public API does not provide login, account creation, custody signing, wallet controls or arbitrary journal posting. Request execution is disabled on the documentation site. ## Accounts, assets and financial evidence A financial account represents an obligation in one network-specific asset. It does not identify a physical wallet. USDC on two different networks represents two distinct asset identities; a shared currency symbol does not permit implicit conversion or cross-network spending. Amounts are decimal strings. Preserve their exact text, and use the asset's supported precision. Versions are strings and may exceed JavaScript's safe integer range. Do not convert either representation through floating point. The account balance is committed financial history, not a calculation of available spending capacity. Arctex coordinates financial reservations and physical execution liquidity. Your application must not authorize spending by subtracting its own pending transfers from a balance read. A transfer state, observed deposit, bridge burn or confirmed blockchain transaction is not a financial posting. Financial consequences come from committed `FinancialEffect` records. Each effect retains its journal, posting line, account, asset, signed amount, classification and typed business origin. Deduplicate `effect_ref` atomically with your own financial posting. Principal, fees and corrections have distinct identities. Your application owns its customer balances, commercial pricing and surrounding business workflow. A completed digital asset transfer does not, by itself, complete a separate fiat payment or provider-funding obligation. Internal operating, hold, pending or transit movements must not become duplicate customer charges. ## Receiving payments Multiple receiving addresses can credit one financial account. Retain the original receiving reference, address, memo and customer mapping; the pooled account alone cannot establish which customer owns an incoming payment. Deposits preserve immutable intake evidence and revisioned attribution. A route or account may be unresolved initially. A later revision can add proven attribution; your application must not reconstruct historical ownership from today's address configuration. A completed credit requires resolved attribution and a committed financial receipt. Use `/v1/deposits` to recover immutable revisions and the deposit GET operation for the current revision. Deduplicate revisions by `(deposit_ref, version)`. Continue watching an existing identity through delayed credit or recovery. Address disablement stops allocation; it does not erase historical attribution or late-deposit obligations. Rotation, review and rejected-deposit returns remain administrative workflows. ## Quotes and transfers Quote creation does not reserve funds or admit execution. Submit only a complete, unexpired `EXECUTABLE` quote. `BLOCKED` and `INDICATIVE` quotes cannot be submitted; missing economics must not be interpreted as zero amounts or fees. | Mode / fee treatment | Meaning and supported scope | | --- | --- | | `FIX_SOURCE` / `ADD_TO_SOURCE` | Amount is source principal before applicable charges. Supported for ordinary crypto and configured bridge routes. | | `FIX_SOURCE` / `DEDUCT_FROM_DESTINATION` | Amount is the inclusive source budget; the recipient receives the resulting net. Supported for ordinary crypto and configured bridge routes. | | `FIX_RECEIVED` / `ADD_TO_SOURCE` | Amount is exact recipient net; the quote calculates required source amounts and charges. Supported for ordinary crypto and configured bridge routes. | | `FIX_RECEIVED` / `DEDUCT_FROM_DESTINATION` | Exact recipient net with required gross-up. Supported by the bridge quoter; ordinary crypto returns `422 UNSUPPORTED_QUOTE_COMBINATION`. | Availability depends on your enabled routes and financial/physical readiness. Fees retain their own asset identity. Do not sum amounts across different assets, infer tenant charges from platform gas costs or recalculate accepted economics. `202 Accepted` means durable transfer admission. It does not promise a committed financial hold, immediate liquidity, broadcast or settlement. Arctex's existing processing owner acquires the required reservations and recovers execution. Accepted instructions, fees and destination remain frozen after quote expiry. One quote admits at most one transfer. Concurrent submissions under different keys can converge on the original transfer and its original client reference. A client reference is correlation, not a financial or execution deduplication identity. Recover with the original key, known transfer or quote-filtered transfer list before considering any replacement. There is no public cancellation endpoint. ## Idempotency request comparison Persist the key, original typed input and local correlation before each POST. Keys are scoped by tenant and operation. Current authorization applies on every replay, while original actor and accepted resolution remain retained. | Replay input | Result | | --- | --- | | Same validated values and field presence, with different JSON whitespace or object member order | Recover the original durable result. | | Different amount text, such as `"100"` instead of `"100.00"` | Different input; return `409 IDEMPOTENCY_CONFLICT`. | | Omitted field instead of an explicitly supplied field | Different input, including a token contract that originally resolved to the same asset. | | Unknown fields, duplicate JSON members or disallowed nulls | Reject the request. | | Original input replayed after catalog or precision changes | Compare retained input and resolution; accepted terms are not repriced. | | Original identity is still being resolved | Return `409 SUBMISSION_IN_PROGRESS`; retry the same request/key. | | Identity has been explicitly retired | Return `410 IDEMPOTENCY_RECORD_EXPIRED`; preserve the fence and request administrative recovery. | A timeout, 503, lost response or decode failure leaves the outcome uncertain. None authorizes a new key or payment. An accepted same-key replay resolves before quote-expiry checks. Do not assume a previously unseen different key works after expiry. ## Webhooks Arctex Webhooks provides `transfer.updated`, `deposit.updated` and `financial_effect.committed`. Resource updates and committed financial effects have different meanings and may arrive in any order. Delivery may repeat. The implemented signing headers are: | Header | Value | | --- | --- | | `X-Callback-Timestamp` | UTC RFC3339Nano delivery timestamp. | | `X-Callback-Algorithm` | `hmac-sha256`. | | `X-Callback-Signature` | Lowercase hexadecimal HMAC-SHA256 over `timestamp + "." + rawBody`. | Verify the original bytes before decoding, using constant-time comparison and your approved timestamp window; the documented signing profile uses five minutes. Support approved overlapping keys during rotation. Never skip verification when key resolution fails. The Go verifier requires an explicit replay window and does not supply a default. After authentication, persist the raw envelope and stable event/effect identities before acknowledging 2xx. Retries retain `event_id`; delivery IDs and signing times change for each attempt. A timestamp window does not replace durable inbox or financial-effect deduplication. Only committed financial receipts produce `financial_effect.committed`. Its data matches the canonical financial-effect GET/list object. Resolve the typed deposit or transfer origin through retained mappings before posting locally; a financial notification can arrive before the resource-update notification. ## Recovery reads `/v1/deposits` recovers immutable deposit revisions. `/v1/financial-effects` recovers immutable committed effects. Save each returned cursor only after all items are durably handled. Continue from it after an empty page or `has_more=false`; that flag means the projection is caught up now, not that the source is complete or that no later corrections can arrive. Cursors bind tenant, actor, account scope, surface and filters. Deposit consumers deduplicate by reference/version; financial consumers deduplicate `effect_ref`. Do not substitute event time, an account version or a transaction hash for a cursor or a committed financial identity. ## Installed retention and delivery policy | Control | Current preview policy | | --- | --- | | Recovery cursor | 24-hour lifetime. Malformed or mismatched cursors return 400; expired or unverifiable cursors return 410. | | Public commands and quote claims | No automatic TTL. Explicit retirement retains the execution fence. | | Deposit revisions, committed effects and callback tasks | No automatic TTL. Legacy or pre-checkpoint history requires explicit adoption. | | Callback defaults | Eight attempts, a ten-second attempt timeout and exponential backoff from one second capped at 300 seconds. Installation settings can override delivery defaults and jitter. | | Retry exhaustion | Failed tasks remain retained for scoped administrative replay with the same event/effect identity. | These are implementation policies, not a production retention or delivery SLA. Before production activation, agree history/restore coverage, receiver inbox retention, supported outage windows, replay availability and escalation ownership. ## Reconciliation after expiry For `RECOVERY_CURSOR_EXPIRED`, preserve your checkpoint, filters, inbox and deduplication state. Pause decisions that depend on stream completeness. Use the approved support channel to reconcile retained source history and financial membership, then establish a replacement checkpoint. Do not silently reset a cursor or treat a partial cursorless history as complete. For `IDEMPOTENCY_RECORD_EXPIRED`, preserve the original key, request, quote and known resource/effect references. Retrieve the transfer or list by quote reference. An empty read is not proof of non-execution. Arctex operations must resolve the original execution and financial obligations before a replacement can be approved. Keep the retired key blocked. ## Consistent reconciliation cutoff Reading a balance and paging effects until `has_more=false` does not establish a financial cutoff. New or backdated commits may exist outside the current projection. Historical `as_of`, account versions, business time and cursors are different coordinates. When a fixed financial proof is required, use the Accounting-backed administrative snapshot procedure: 1. Start from an evidenced baseline for one authorized account and asset: balance, source version and exact committed posting membership. 2. Obtain a sealed source snapshot containing the next balance/version and complete posting membership. Compare actual memberships to identify added effects. 3. Recover every effect in that membership. Missing projection data remains unresolved; a caught-up page cannot replace source evidence. 4. Verify `new balance = baseline balance + signed deltas of all added effects`, using exact arithmetic and effect-ID deduplication. Include fees and corrections. 5. Preserve the snapshot and membership as the next baseline. Concurrent commits outside it belong to a later proof, even if their business time is earlier. This procedure adds no public snapshot endpoint. If complete source evidence or baseline history is unavailable, keep reconciliation unresolved and escalate. ## Errors and operational attention Use `Error.code` for handling; message text is explanatory. Preserve the original identity through uncertain responses and contact support through the approved onboarding channel with request ID and resource references, without secrets or sensitive payment payloads. | Code / category | Action | | --- | --- | | `INVALID_REQUEST`, `INVALID_INPUT`, `INVALID_PRECISION`, `UNSUPPORTED_QUOTE_COMBINATION` | Correct rejected input. Resolve any earlier uncertain submission first. | | `UNAUTHENTICATED`, `PERMISSION_DENIED`, `NOT_FOUND` | Check credentials, scope and identity. Absence does not establish non-execution. | | `IDEMPOTENCY_CONFLICT`, `QUOTE_CLAIM_CONFLICT` | Recover the original input and transfer. Do not repurpose the identity. | | `SUBMISSION_IN_PROGRESS`, `DEPENDENCY_UNAVAILABLE`, transport uncertainty | Retry or recover the original request/key with backoff. | | `QUOTE_EXPIRED`, `QUOTE_NOT_EXECUTABLE` | Resolve prior acceptance before requesting new terms for a genuinely new operation. | | `INSUFFICIENT_FUNDS`, `LIQUIDITY_UNAVAILABLE`, `COMPLIANCE_REVIEW_REQUIRED` | Follow the admission response or retained transfer's attention guidance; no assumed release or replacement. | | `RECOVERY_CURSOR_EXPIRED`, `IDEMPOTENCY_RECORD_EXPIRED` | Follow the expiry procedures above. | | `RATE_LIMITED` | Respect `Retry-After` when supplied and retain the same request/key. | `attention` provides a reason, safe message and action: `WAIT`, `CONTACT_SUPPORT` or `NONE`. Follow both state and committed financial evidence. Operational review, returns, reservation release and compensation remain with the authorized owners; an attention code or elapsed time cannot authorize a refund. ## v1 compatibility and unknown values The draft document version is independent of `/v1`. The preview can change through reviewed revisions; it is not a production compatibility claim. Published closed response fields, enums, financial classifications and error/attention catalogs must not be expanded silently within a released `/v1` contract. Preserve unknown fields and raw response evidence. Unknown states, origins or financial meanings must not become default success, refunds or customer postings. Quarantine dependent decisions and retain the original request and recovery checkpoint until the record is understood. Consumer tolerance does not authorize breaking producer changes. ## Go integration kit The Arctex Go integration kit contains the contract, generated client, callback and financial interpretation guards, portable tests and reproducible source fingerprints. The preview module currently uses `github.com/lazysteff/crypto-processing/publicapi`; this existing import path is retained for compatibility. No `arctex-go` registry release is claimed. Use the installation-issued endpoint and credential with explicit HTTP deadlines. The client refuses redirects, retains bounded error evidence and rejects oversized responses, including a valid JSON prefix. It preserves decimal/version strings and optional field presence. It does not implement your retry loop, customer ledger or posting authorization. Verify an issued bundle's checksums and retain its contract version and input hashes with your integration build. Run your own application acceptance before adopting an updated kit.