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

# Grant

> Install a bounded Cinder agent, not a native credential.

**Carrier:** `POST /v1/exchange` (encrypted binary).

**Permission:** Owner only.

Install a bounded Cinder agent, not a native credential. The same command is available over [WebSocket](/api/websocket).

<Note>
  Fields below describe the SDK request **before encryption** and the decoded reply.
  The HTTP body is encrypted binary `application/octet-stream`, not JSON.
  Use a verified [SDK client](/quickstart); the interactive playground is disabled.
</Note>

<RequestExample>
  ```ts SDK request theme={null}
  const response = await client.request({ id: ctx.id, epoch: ctx.epoch, expiresAt: ctx.expiresAt,
      command: { kind: 'grant', grant: {
        key: ctx.agentPublicKey, methods: READ | TRADE | CANCEL, market: ctx.market,
        maximumLots: 2n, maximumFee: 1n, maximumOrders: 10n,
        expiresAt: ctx.agentExpiresAt } } });
  ```
</RequestExample>

<ResponseExample>
  ```ts Decoded receipt theme={null}
  ({
    kind: 'receipt',
    id: ctx.id,
    digest: recordedIntentDigest,
    policy: approvedPolicyVersion,
    outcome: 'complete',
    filled: 0n,
    paid: 0n,
    railFees: 0n,
    feeCap: 0n,
    possiblyExposed: false,
    allowPartial: false,
  })
  ```

  ```ts Encrypted application error theme={null}
  ({ kind: 'error', code: 'unauthorized' })
  ```
</ResponseExample>

## Request fields

The client supplies the configured domain, account, policy, signer and verified
session binding, and signs the canonical [envelope](/api/authentication).

<ParamField body="id" type="Uint8Array (32 bytes)" required>
  Nonzero private request ID. Retain it for an exact retry; use a distinct ID for a different intent.
</ParamField>

<ParamField body="epoch" type="bigint (u64)" required>
  Current account authority epoch.
</ParamField>

<ParamField body="expiresAt" type="bigint (u64)" required>
  Authentication expiry in milliseconds, within the verified session and deployment limits.
</ParamField>

<ParamField body="command.kind" type="&#x22;grant&#x22;" required>
  Command discriminator.
</ParamField>

<ParamField body="command.grant" type="Grant" required>
  Scoped Cinder agent terms.

  <Expandable title="Grant fields">
    <ParamField body="key" type="Uint8Array (32 bytes)" required>
      Separate valid Ed25519 agent public key, not owner key.
    </ParamField>

    <ParamField body="methods" type="number" required>
      Nonzero bitmask: READ=1, TRADE=2, CANCEL=4, no other bits.
    </ParamField>

    <ParamField body="market" type="Uint8Array (32 bytes)" required>
      One configured market.
    </ParamField>

    <ParamField body="maximumLots" type="bigint (u64)" required>
      Positive maximum absolute lots per admitted order.
    </ParamField>

    <ParamField body="maximumFee" type="bigint (i128)" required>
      Nonnegative maximum fee per lot in quote atoms.
    </ParamField>

    <ParamField body="maximumOrders" type="bigint (u64)" required>
      Positive lifetime accepted-order budget in this epoch.
    </ParamField>

    <ParamField body="expiresAt" type="bigint (u64)" required>
      Absolute expiry within governed maximum duration.
    </ParamField>
  </Expandable>
</ParamField>

## Response fields

The example uses illustrative quote atoms and configured IDs, not live venue data.
A receipt records operation progress; acceptance is not execution or payment.

<ResponseField name="kind" type="&#x22;receipt&#x22;" required>
  Response discriminator.
</ResponseField>

<ResponseField name="id" type="Uint8Array (32 bytes)" required>
  Durable operation ID. For an operation lookup, this is the target ID, not the query ID.
</ResponseField>

<ResponseField name="digest" type="Uint8Array (32 bytes)" required>
  Commitment to the immutable economic intent.
</ResponseField>

<ResponseField name="policy" type="number (u32)" required>
  Governed policy version.
</ResponseField>

<ResponseField name="outcome" type="Outcome" required>
  `rejected`, `accepted`, `dispatched`, `acknowledged`, `partial`, `complete` or `unknown`. See [lifecycle](/api/lifecycle).
</ResponseField>

<ResponseField name="filled" type="bigint (i64)" required>
  Actual attributed signed lots, not requested quantity.
</ResponseField>

<ResponseField name="paid" type="bigint (i128)" required>
  Qualified net payment to the beneficiary, in quote atoms.
</ResponseField>

<ResponseField name="railFees" type="bigint (i128)" required>
  Actual customer-paid payout rail fees; not ordinary trading fees.
</ResponseField>

<ResponseField name="feeCap" type="bigint (i128)" required>
  Declared fee cap: absolute requested lots × fee-per-lot for orders, or extra rail-fee cap for payouts. Not the amount charged.
</ResponseField>

<ResponseField name="possiblyExposed" type="boolean" required>
  Whether the operation may have escaped for external execution. False alone is not a final settlement guarantee.
</ResponseField>

<ResponseField name="allowPartial" type="boolean" required>
  The recorded payout partial-dispatch consent. False for unrelated commands.
</ResponseField>

## Behavior

Durable receipt; accepted terms live in the protected journal. Exact order retries do not consume another budget unit. An existing key cannot be silently overwritten in the same epoch. No payout, leverage, redelegation or admin permission. Import READ, TRADE and CANCEL from the SDK for this example.

## Errors and reconciliation

[Typed errors](/api/errors) are returned inside the encrypted reply, not as
field-specific HTTP status codes. Invalid fields, expired or out-of-scope authority,
conflicting intent IDs and unavailable required evidence fail closed.

A delivery error or timeout is **not a rejection**. Reconnect with fresh attestation
and reconcile the original operation ID before any economic retry.
See [lifecycle](/api/lifecycle), [limits](/api/limits) and [availability](/status).


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