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

# Choose an integration path

> Choose between the TypeScript SDK, indexed API data, transaction schemas, and direct program calls.

Choose the shallowest integration that meets your product's needs. Most data clients do not need to implement record handling or exact swap math.

## Compare the paths

| Path                 | Start here                                                                                                                | Your application owns                                                                  |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| REST API             | Public pool and token discovery, plus invited access and an API token for routes, history, balances, positions, and swaps | Credential storage, caching, retries, and exact-value parsing                          |
| TypeScript SDK       | A typed client for reads, swaps, claims, and liquidity transactions                                                       | Keys or wallet connection, credentials, finality handling, and recovery storage        |
| Transaction schemas  | `GET /schema/trading` plus a wallet or proving client                                                                     | Records, signing, proving, submission, claims, recovery, and reconciliation            |
| Direct program calls | Chain access, contract-compatible types, and the deployed program ABI                                                     | The complete client boundary, including mappings, math, records, and transaction state |

<Note>
  Start with the [REST API quickstart](../rest/quickstart) for data. Use the [TypeScript SDK](../sdk/typescript-client) when your application submits transactions. Direct program calls are for clients that need control below the SDK surface.
</Note>

## REST API

The API is the shortest path to indexed market state. It is appropriate for backends, bots, dashboards, explorers, and applications that do not submit Shield transactions.

Start with:

1. [List pools](../rest/quickstart).
2. [Create an API token](../rest/authentication) for routes and authenticated data.
3. [Handle pagination and retries](../rest/pagination-and-errors).
4. Use the generated API reference for exact parameters and responses.

The API can become unavailable or lag chain finality. It does not remove the need to validate execution-critical state before signing a transaction.

## TypeScript SDK

`@provablehq/shield-swap-sdk` adds Shield Swap actions to a Veil client. It handles token and pool discovery, import resolution, local record selection, confidential addresses, swap planning, claims, and the position lifecycle.

The SDK supports local keys and connected wallets. A local process must keep its confidential-address store and monitor transaction finality. A wallet integration delegates keys, records, and proofs to the wallet.

Continue with [TypeScript SDK setup](../sdk/typescript-client), [swaps](../sdk/swaps), and [liquidity](../sdk/liquidity).

## Transaction schemas

Use `GET /schema/trading` and `GET /schema/trading/{id}` when your wallet or application wants current input definitions for the configured deployment.

The schema does not perform the transaction. Your client still must:

* discover and reserve unspent token records
* preserve change and replacement records
* construct exact values and program identifiers
* sign and prove the transaction
* submit once and track accepted, rejected, or unknown state
* claim pending swap output
* reconcile public mappings with wallet-held records

Continue with [Transaction execution](./transaction-execution) and [User entrypoints](./user-entrypoints).

## Direct program calls

Use the direct path when the application must operate independently of the API or mirror contract behavior exactly.

<Steps>
  <Step title="Bind the integration to one deployment">
    Record the network, program ID, edition, checksum, dependency revisions, and storage schema. Do not treat two deployments with the same source name as interchangeable.

    The current Q128.128 fee-growth layout is incompatible with scalar fee-growth deployments and requires a fresh deployment.
  </Step>

  <Step title="Generate complete types and parsers">
    Mirror nested Leo records and structs, including `u256::U256`, `MerkleProof`, the immutable `PositionNFT.withdrawal`, and `MintComplianceRecord` where investigator records are handled.

    Parse nested structs structurally. Do not split Leo values on commas inside braces. Represent `u128` and `i128` with arbitrary-precision integers.
  </Step>

  <Step title="Read the required mappings">
    Load pool identity, slot state, initialized ticks, positions, pending swap outputs, token settings, and control state required by the task.

    Version parsers by deployment checksum or release, not by a repository branch name.
  </Step>

  <Step title="Mirror amount and swap math exactly">
    Use native token base units in contract math. Apply display decimals only at the interface boundary. Match fixed-point operations, rounding direction, tick limits, price-limit rules, and iteration caps.

    Single-hop execution uses five swap iterations. Multi-hop execution uses three iterations per hop. Reaching an initialized tick exactly at the price limit completes the crossing.
  </Step>

  <Step title="Own record state">
    Discover records for the signer, verify token and amount, prevent double selection, preserve change, and mark a record spent only after acceptance is known.

    Every position change consumes a `PositionNFT`. Store the replacement returned by increase, decrease, or collect.
  </Step>

  <Step title="Create and retain the confidential address factor">
    Derive the public confidential address from the exact program address, domain constant, signer, and factor. Persist the factor until claim succeeds and never reuse the resulting address.

    A deterministic factor derived by a test client is a client convention, not a contract rule.
  </Step>

  <Step title="Treat swap and claim as one user workflow">
    After swap acceptance, read `swap_outputs[swap_id]` and use its exact stored fields to construct the claim. Persist pending claims across restarts and network failures.
  </Step>

  <Step title="Verify controls and final state">
    Read global, token, pair, pool, and position controls before construction. Refresh them before retrying because state can change before finalization.

    A visible success requires both the expected public mapping change and possession of the expected output records. Test routed calls where `caller != signer`.
  </Step>
</Steps>

## Privacy boundary

Participant addresses are confidential from ordinary public mappings in the intended flow. Trade amounts, routes, pools, output and refund amounts, timing, and market state remain public.

Read [Protocol boundaries](../start/protocol-boundaries) before writing product or privacy claims.