Nitrolite

https://docs.yellow.org/docs/protocol/
Admin
Nitrolite is a state channel protocol that enables off-chain interactions between participants with...
Tokens:72,452
Snippets:519
Trust Score:8.9
Update:10 months ago
Show doc for...
Tokens:
Raw
### SessionKeyInfo Structure Example

Source: https://docs.yellow.org/docs/protocol/off-chain/queries

An example of the SessionKeyInfo structure, which defines session key details including ID, session key address, application name, allowances, scope, and timestamps for creation and expiration.

```json
{
  "id": 1,
  "session_key": "0x9876543210fedcba...",
  "application": "Chess Game",
  "allowances": [
    {"asset": "usdc", "allowance": "100.0", "used": "45.0"}
  ],
  "scope": "app.create,transfer",
  "expires_at": "2023-05-02T12:00:00Z",
  "created_at": "2023-05-01T12:00:00Z"
}
```

--------------------------------

### Fund Distribution Example

Source: https://docs.yellow.org/docs/protocol/off-chain/app-sessions

This example illustrates the flow of funds during the closure of an app session. It shows how balances change in participants' unified accounts and how the session account is depleted and closed.

```text
Before Closure:
  Alice's Unified Account:
    Balance: 100 USDC
  
  App Session Account 0x98765:
    Alice: 100 USDC
    Bob: 100 USDC
    Total: 200 USDC
  
  Close with final allocations:
    Alice: 180 USDC
    Bob: 20 USDC
  
After Closure:
  Alice's Unified Account:
    Balance: 280 USDC (100 + 180 received from session)
      
  Bob's Unified Account:
    Balance: 20 USDC (received from session)
    
  App Session Account 0x98765:
    Closed (Balance: 0 USDC)
```

--------------------------------

### Channel State Example (Solidity)

Source: https://docs.yellow.org/docs/protocol/protocol-reference

Illustrates how to set the `state.intent` field for different channel lifecycle stages. The examples show setting the intent for channel creation (`INITIALIZE`) and for a closing state (`FINALIZE`), demonstrating the usage of the `StateIntent` enumeration.

```solidity
// Creation state
state.intent = 1  // INITIALIZE
state.version = 0
state.data = "0x"  // Empty for basic channels

// Closing state
state.intent = 3  // FINALIZE
state.version = currentVersion + 1
state.data = "0x"

```

--------------------------------

### Get Ledger Entries Structure (Example)

Source: https://docs.yellow.org/docs/protocol/off-chain/queries

Illustrates the structure of a single ledger entry, including its unique ID, account details, asset, participant, and the credit or debit amount. This is crucial for detailed financial reconciliation and audit trails.

```json
{
  "ledger_entries": [
    {
      "id": 123,
      "account_id": "0x742d35Cc...",
      "account_type": 1000,
      "asset": "usdc",
      "participant": "0x742d35Cc...",
      "credit": "100.0",
      "debit": "0.0",
      "created_at": "2023-05-01T12:00:00Z"
    }
  ]
}
```

--------------------------------

### Get Session Keys - JavaScript Example

Source: https://docs.yellow.org/docs/protocol/off-chain/queries

Fetches all active (non-expired) session keys for the authenticated user. This method provides details on each session key including its address, associated application, spending allowances, current usage, expiration, and permissions. It is primarily used for managing delegated keys and monitoring spending caps.

```javascript
async function getSessionKeys(offset = 0, limit = 10, sort = "desc") {
  const response = await fetch("/api/get_session_keys", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      // Include authentication headers here
    },
    body: JSON.stringify({
      offset: offset,
      limit: limit,
      sort: sort,
    }),
  });
  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }
  return await response.json();
}

// Example usage:
getSessionKeys().then(data => {
  console.log("Session Keys:", data.session_keys);
}).catch(error => {
  console.error("Failed to fetch session keys:", error);
});
```

--------------------------------

### Get Ledger Balances Structure (Example)

Source: https://docs.yellow.org/docs/protocol/off-chain/queries

This snippet shows the structure of the balance object returned by the API, detailing the asset and its corresponding amount. It's used to display a user's current balances or check available funds.

```json
{
  "ledger_balances": [
    {
      "asset": "usdc",
      "amount": "100.0"
    }
  ]
}
```

--------------------------------

### Chess Game Closure Example

Source: https://docs.yellow.org/docs/protocol/off-chain/app-sessions

An example demonstrating fund distribution in a chess game scenario upon session closure. It highlights how initial funds are reallocated based on the game's outcome, including commissions.

```text
Initial:
  White: 100 USDC
  Black: 100 USDC
  Judge: 0 USDC
  Total: 200 USDC
  
Final (White wins):
  White: 190 USDC (won 90)
  Black: 0 USDC (lost 100)
  Judge: 10 USDC (5% commission)
  Total: 200 USDC ✓
```

--------------------------------

### Get Ledger Transactions Structure (Example)

Source: https://docs.yellow.org/docs/protocol/off-chain/queries

Shows the structure of a ledger transaction, providing a user-friendly view of financial activities like transfers, deposits, and withdrawals. This differs from ledger entries by offering a simplified overview.

```json
{
  "ledger_transactions": [
    {
      "id": "tx123",
      "type": "transfer",
      "from": "0xAlice...",
      "to": "0xBob...",
      "asset": "usdc",
      "amount": "50.0",
      "created_at": "2023-05-01T12:05:00Z"
    }
  ]
}
```

--------------------------------

### Get RPC History - JavaScript Example

Source: https://docs.yellow.org/docs/protocol/off-chain/queries

Fetches recent RPC invocations for the authenticated user, including signed request and response payloads. This method is useful for debugging client integrations and maintaining audit trails. Parameters include offset, limit, and sort order for pagination and filtering.

```javascript
async function getRpcHistory(offset = 0, limit = 10, sort = "desc") {
  const response = await fetch("/api/get_rpc_history", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      // Include authentication headers here
    },
    body: JSON.stringify({
      offset: offset,
      limit: limit,
      sort: sort,
    }),
  });
  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }
  return await response.json();
}

// Example usage:
getRpcHistory(0, 25, "asc").then(data => {
  console.log("RPC History:", data.rpc_entries);
}).catch(error => {
  console.error("Failed to fetch RPC history:", error);
});
```

--------------------------------

### Canonical JSON Encoding Example

Source: https://docs.yellow.org/docs/protocol/off-chain/message-format

Provides examples of JSON encoding for signing, highlighting the 'Consistent' version which adheres to ordering, no whitespace, and no trailing commas, and the 'Inconsistent' version which would result in a different hash.

```json
[1,"transfer",{"amount":"100","asset":"usdc","destination":"0x..."},1699123456]
```

```json
[
  1,
  "transfer",
  { "destination": "0x...", "amount": "100", "asset": "usdc" },
  1699123456
]
```

--------------------------------

### GET /get_config

Source: https://docs.yellow.org/docs/protocol/off-chain/queries

Retrieves the clearnode's configuration, including the broker address and supported blockchains with their custody and adjudicator contracts.

```APIDOC
## GET /get_config

### Description
Retrieves the clearnode's configuration: broker address plus supported blockchains and their custody/adjudicator contracts.

### Method
GET

### Endpoint
/get_config

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **broker_address** (string) - Clearnode's wallet address
- **networks** (array<BlockchainInfo>) - List of supported blockchain networks

#### BlockchainInfo Structure
- **chain_id** (uint32) - Network identifier
- **name** (string) - Human-readable blockchain name
- **custody_address** (string) - Custody contract address on this chain
- **adjudicator_address** (string) - Adjudicator contract address on this chain

#### Response Example
```json
{
  "broker_address": "0xbbbb567890abcdef...",
  "networks": [
    {
      "chain_id": 137,
      "name": "Polygon",
      "custody_address": "0xCustodyContractAddress...",
      "adjudicator_address": "0xAdjudicatorAddress..."
    }
  ]
}
```
```

--------------------------------

### GET /app_sessions

Source: https://docs.yellow.org/docs/protocol/off-chain/queries

Lists all app sessions for a participant, sorted by creation date.  Supports filtering by status and pagination.

```APIDOC
## GET /app_sessions

### Description
Lists all app sessions for a participant, sorted by creation date (newest first by default). Optionally filter by status (open/closed). Returns complete session information including participants, voting weights, quorum, protocol version, and current state. Supports pagination for large result sets.

### Method
GET

### Endpoint
/app_sessions

### Parameters
#### Query Parameters
- **participant** (string (address)) - Optional - Filter by participant wallet address.
- **status** (string) - Optional - Filter by status. Allowed values: "open", "closed"
- **offset** (number) - Optional - Pagination offset (default: 0)
- **limit** (number) - Optional - Number of sessions to return (max 100, default: 10)
- **sort** (string) - Optional - Sort order by created_at (default: "desc")

### Response
#### Success Response (200)
- **app_sessions** (array<AppSessionInfo>) - List of app sessions. See AppSessionInfo structure below.

#### Response Example
```json
{
  "app_sessions": [
    {
      "app_session_id": "0x9876543210fedcba...",
      "application": "NitroliteChess",
      "status": "open",
      "participants": ["0x742d35Cc...", "0x8B3192f2..."],
      "weights": [50, 50, 100],
      "quorum": 100,
      "protocol": "NitroRPC/0.4",
      "challenge": 86400,
      "version": 5,
      "nonce": 1699123456789,
      "session_data": "{\"gameType\":\"chess\",\"turn\":\"white\"}",
      "created_at": "2023-05-01T12:00:00Z",
      "updated_at": "2023-05-01T14:30:00Z"
    }
  ]
}
```

#### AppSessionInfo
- **app_session_id** (string) - Unique identifier
- **application** (string) - Application identifier
- **status** (string) - Current status
- **participants** (array<address>) - All participant wallet addresses
- **weights** (array<int64>) - Voting weights per participant
- **quorum** (uint64) - Required weight for state updates
- **protocol** (string) - Protocol version
- **challenge** (uint64) - Challenge period in seconds
- **version** (number) - Current state version
- **nonce** (uint64) - Unique session identifier
- **session_data** (string) - Current application state
- **created_at** (string (timestamp)) - Creation timestamp
- **updated_at** (string (timestamp)) - Last update timestamp
```

--------------------------------

### GET /get_assets

Source: https://docs.yellow.org/docs/protocol/off-chain/queries

Retrieves all supported assets and their configurations across supported blockchains. Allows filtering by a specific chain ID.

```APIDOC
## GET /get_assets

### Description
Retrieves all supported assets and their configurations across supported blockchains.

### Method
GET

### Endpoint
/get_assets

### Parameters
#### Path Parameters
None

#### Query Parameters
- **chain_id** (uint32) - Optional - Filter by specific chain. If omitted, returns assets for all chains.

#### Request Body
None

### Request Example
```bash
GET /get_assets?chain_id=137
```

### Response
#### Success Response (200)
- **assets** (array<Asset>) - List of supported assets

#### Asset Structure
- **token** (string) - Token contract address
- **chain_id** (uint32) - Blockchain network identifier
- **symbol** (string) - Token symbol
- **decimals** (uint8) - Number of decimal places

#### Response Example
```json
{
  "assets": [
    {
      "token": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
      "chain_id": 137,
      "symbol": "usdc",
      "decimals": 6
    }
  ]
}
```
```

--------------------------------

### Example Governance: DAO-like Voting

Source: https://docs.yellow.org/docs/protocol/off-chain/app-sessions

Shows a DAO-like voting structure where a weighted majority of participants is required to approve state updates. This is suitable for collaborative fund management.

```plaintext
Participants: [User1, User2, User3, User4, Contract]
Weights: [20, 25, 30, 25, 0]
Quorum: 51
```

--------------------------------

### Get User Tag - JavaScript Example

Source: https://docs.yellow.org/docs/protocol/off-chain/queries

Retrieves the authenticated user's unique alphanumeric tag. This tag serves as a human-readable alternative to wallet addresses for transfer operations, enhancing user experience. The tag is automatically generated upon the first interaction with a clearnode and remains constant.

```javascript
async function getUserTag() {
  const response = await fetch("/api/get_user_tag", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      // Include authentication headers here
    },
  });
  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }
  return await response.json();
}

// Example usage:
getUserTag().then(data => {
  console.log("User Tag:", data.tag);
  // This tag can be used in transfer operations:
  // transfer({ destination_user_tag: data.tag, ... });
}).catch(error => {
  console.error("Failed to fetch user tag:", error);
});
```

--------------------------------

### Example Governance: Simple Two-Player Game

Source: https://docs.yellow.org/docs/protocol/off-chain/app-sessions

Illustrates a simple two-player game governance model where both participants must sign every state update. This is suitable for direct one-on-one games.

```plaintext
Participants: [Alice, Bob]
Weights: [1, 1]
Quorum: 2
```

--------------------------------

### Example Governance: Multi-Party Escrow

Source: https://docs.yellow.org/docs/protocol/off-chain/app-sessions

Presents a multi-party escrow governance model where any two out of three participants can approve state updates. This allows for flexible dispute resolution.

```plaintext
Participants: [Buyer, Seller, Arbiter]
Weights: [40, 40, 50]
Quorum: 80
```

--------------------------------

### Transferring Funds with User Tag - JavaScript Example

Source: https://docs.yellow.org/docs/protocol/off-chain/queries

Demonstrates how to use a user tag as a destination for fund transfers, providing a more human-readable alternative to full wallet addresses. This simplifies payment operations and improves user experience, similar to using usernames in payment applications.

```javascript
async function transferWithUserTag(tag, asset, amount) {
  // Assume 'transfer' is a pre-defined function that handles the actual transfer logic
  // For demonstration, we'll simulate the call.
  console.log(`Simulating transfer to tag: ${tag} for asset: ${asset}, amount: ${amount}`);
  
  // In a real scenario, you would call your transfer function like this:
  /*
  const result = await transfer({
    destination_user_tag: tag,
    asset: asset,
    amount: amount,
    // other transfer parameters...
  });
  return result;
  */
  
  // Placeholder for successful simulation
  return { success: true, message: `Transfer initiated to ${tag}` };
}

// Example usage:
transferWithUserTag("UX123D", "usdc", "50.0").then(result => {
  console.log(result.message);
}).catch(error => {
  console.error("Transfer failed:", error);
});

// Contrast with using a full address:
async function transferWithAddress(address, asset, amount) {
  console.log(`Simulating transfer to address: ${address} for asset: ${asset}, amount: ${amount}`);
  /*
  const result = await transfer({
    destination: address,
    asset: asset,
    amount: amount,
    // other transfer parameters...
  });
  return result;
  */
  return { success: true, message: `Transfer initiated to ${address}` };
}

// Example usage with address:
transferWithAddress("0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb", "usdc", "50.0").then(result => {
  console.log(result.message);
}).catch(error => {
  console.error("Transfer failed:", error);
});
```

--------------------------------

### Example Governance: Game with Judge

Source: https://docs.yellow.org/docs/protocol/off-chain/app-sessions

Demonstrates a governance model where a single judge has full control over state updates. This is useful for games where the application logic dictates the outcome.

```plaintext
Participants: [Alice, Bob, Judge]
Weights: [0, 0, 100]
Quorum: 100
```

--------------------------------

### Example Transaction Response (JSON)

Source: https://docs.yellow.org/docs/protocol/off-chain/transfers

This JSON structure represents an example response containing an array of ledger transactions. Each transaction object details the sender, recipient, asset, amount, and timestamp of a transfer.

```json
{
  "transactions": [
    {
      "id": 1,
      "tx_type": "transfer",
      "from_account": "0x1234567890abcdef...",
      "from_account_tag": "NQKO7C",
      "to_account": "0x9876543210abcdef...",
      "to_account_tag": "UX123D",
      "asset": "usdc",
      "amount": "50.0",
      "created_at": "2023-05-01T12:00:00Z"
    },
    {
      "id": 2,
      "tx_type": "transfer",
      "from_account": "0x1234567890abcdef...",
      "from_account_tag": "NQKO7C",
      "to_account": "0x9876543210abcdef...",
      "to_account_tag": "UX123D",
      "asset": "eth",
      "amount": "0.1",
      "created_at": "2023-05-01T12:00:00Z"
    }
  ]
}
```

--------------------------------

### Example Governance: Watch Tower

Source: https://docs.yellow.org/docs/protocol/off-chain/app-sessions

Illustrates a dual-mode governance model with a 'Watch Tower'. Normal operations require cooperation between specific participants, while the Watch Tower can act alone in emergencies.

```plaintext
Participants: [Alice, Bob, WatchTower]
Weights: [40, 40, 100]
Quorum: 80
```

--------------------------------

### Nitro RPC Example Request Message

Source: https://docs.yellow.org/docs/protocol/off-chain/message-format

This example demonstrates a complete Nitro RPC request message for an 'auth_request'. It shows the structure of the 'req' array with specific parameters and includes a sample signature in the 'sig' array.

```json
{
  "req": [
    1,
    "auth_request",
    {
      "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      "session_key": "0x9876543210fedcba9876543210fedcba98765432",
      "application": "trading-dex",
      "allowances": [
        {"asset": "usdc", "amount": "1000.0"},
        {"asset": "eth", "amount": "0.5"}
      ],
      "scope": "transfer,app.create",
      "expires_at": 1762417328123
    },
    1699123456789
  ],
  "sig": [
    "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef01"
  ]
}
```

--------------------------------

### Double-Entry Bookkeeping Example (Conceptual)

Source: https://docs.yellow.org/docs/protocol/off-chain/queries

Demonstrates the fundamental concept of double-entry bookkeeping as applied in the Yellow Protocol. Each transaction results in two entries, ensuring that total debits always equal total credits, maintaining accounting accuracy.

```text
Transfer: Alice sends 50 USDC to Bob  
  
Entry 1 (Alice's ledger):  
  account_id: Alice's address  
  asset: usdc  
  credit: 0.0  
  debit: 50.0  
    
Entry 2 (Bob's ledger):  
  account_id: Bob's address  
  asset: usdc  
  credit: 50.0  
  debit: 0.0  
```

--------------------------------

### Error Response Structure and Examples

Source: https://docs.yellow.org/docs/protocol/off-chain/message-format

Illustrates the structure of an error response from a clearnode, where the method is set to 'error' and the result object contains a descriptive error message. Includes examples for 'Authentication Required', 'Insufficient Balance', and 'Method Not Found'.

```json
{
  "res": [
    requestId,
    "error",
    {
      "error": "Error description message"
    },
    timestamp
  ],
  "sig": ["0xServerSignature..."]
}
```

```json
{
  "res": [
    5,
    "error",
    {
      "error": "Authentication required: session not established"
    },
    1699123456789
  ],
  "sig": ["0xServerSignature..."]
}
```

```json
{
  "res": [
    12,
    "error",
    {
      "error": "Insufficient balance: required 100 USDC, available 75 USDC"
    },
    1699123456790
  ],
  "sig": ["0xServerSignature..."]
}
```

```json
{
  "res": [
    8,
    "error",
    {
      "error": "Method not found: 'invalid_method'"
    },
    1699123456791
  ],
  "sig": ["0xServerSignature..."]
}
```

--------------------------------

### Create Payment Channel - Off-chain Preparation

Source: https://docs.yellow.org/docs/protocol/off-chain/channel-methods

Initiates the creation of a payment channel by preparing and signing the initial channel state off-chain. This step involves the clearnode validating the request and generating a channel configuration. The user receives the channel data and clearnode's signature, which are then used for on-chain execution.

```json
{
  "participants": ["0x742d35Cc...", "0x123456Cc..."],
  "adjudicator": "0xAdjudicator123...",
  "challenge": 86400,
  "nonce": 1699123456
}

```

```json
{
  "intent": 1,
  "version": 0,
  "state_data": "0x",
  "allocations": [
    {"participant": "0x742d35Cc...", "token": "0x2791Bca1...", "amount": "0"},
    {"participant": "0x123456Cc...", "token": "0x2791Bca1...", "amount": "0"}
  ]
}

```

--------------------------------

### Signature Order Example (Solidity)

Source: https://docs.yellow.org/docs/protocol/protocol-reference

Highlights the critical requirement for signature order to match the participant array order. `state.sigs[0]` must correspond to the signature of `participants[0]`, and `state.sigs[1]` to `participants[1]`. Incorrect ordering will lead to transaction failures.

```solidity
state.sigs[0] = creator_signature   // Must be from participants[0]
state.sigs[1] = clearnode_signature // Must be from participants[1]

```

--------------------------------

### Submit App State Request (Deposit Example, JSON)

Source: https://docs.yellow.org/docs/protocol/communication-flows

An example JSON request to update the state of an app session, specifically for a 'deposit' intent in version 0.4. This increases the total sum, requiring the depositor's signature and available balance.

```json
{
  "req": [2,"submit_app_state",{
    "app_session_id": "0xSession",
    "intent": "deposit",
    "version": 2,
    "allocations": [
      {"participant": "0xA","asset": "usdc","amount": "150.0"},
      {"participant": "0xB","asset": "usdc","amount": "100.0"}
    ]
  },1699123456790],
  "sig": ["0xUserSig","0xCoSig"]
}

```

--------------------------------

### GET /get_channels

Source: https://docs.yellow.org/docs/protocol/off-chain/queries

Lists all channels for a specific participant address across all supported chains. Supports pagination.

```APIDOC
## GET /get_channels

### Description
Lists all channels for a specific participant address across all supported chains.

### Method
GET

### Endpoint
/get_channels

### Parameters
#### Path Parameters
None

#### Query Parameters
- **participant_address** (string) - Required - The address of the participant whose channels to list.
- **limit** (int) - Optional - Maximum number of channels to return (defaults to 10, max 100).
- **offset** (int) - Optional - The number of channels to skip (defaults to 0).

#### Request Body
None

### Request Example
```bash
GET /get_channels?participant_address=0xYourParticipantAddress...&limit=20&offset=10
```

### Response
#### Success Response (200)
- **channels** (array<Channel>) - List of channels matching the criteria.

#### Channel Structure (Example)
- **channel_id** (string) - Unique identifier for the channel.
- **participant1** (string) - Address of the first participant.
- **participant2** (string) - Address of the second participant.
- **chain_id** (uint32) - The chain the channel is on.
- **balance** (object) - Current balance information for the channel.
  - **amount** (string) - The amount.
  - **token** (string) - The token contract address.
- **status** (string) - The current status of the channel (e.g., "open", "closed").

#### Response Example
```json
{
  "channels": [
    {
      "channel_id": "0xChannelId1...",
      "participant1": "0xParticipant1Address...",
      "participant2": "0xParticipant2Address...",
      "chain_id": 137,
      "balance": {
        "amount": "1000000",
        "token": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174"
      },
      "status": "open"
    }
  ]
}
```
```

--------------------------------

### POST /auth/verify

Source: https://docs.yellow.org/docs/protocol/off-chain/authentication

Completes the authentication flow by submitting a signed challenge. If valid, the session key can be used for subsequent requests.

```APIDOC
## POST /auth/verify

### Description
Completes the authentication flow by submitting the signed challenge from `auth_challenge`. If the signature is valid and matches the registered session key, the authentication is complete and the session key can be used to sign subsequent requests. This proves the client controls the private key without ever transmitting it.

### Method
POST

### Endpoint
/auth/verify

### Parameters
#### Query Parameters
- **challenge** (string) - Required - The challenge_message received from auth_challenge. Must be the exact challenge from Step 2.
- **jwt** (string) - Optional - Existing JWT for re-login without signature. If provided, signature is not required.

#### Request Body
- **sig** (string) - Required (if jwt is omitted) - EIP-712 signature signed by the main wallet.

### Request Example
```json
{
  "sig": "0x..."
}
```

### Response
#### Success Response (200)
- **address** (string) - Authenticated user's main wallet address.
- **session_key** (string) - Confirmed session key wallet address.
- **jwt_token** (string) - JWT token for authenticated API calls. Store securely; validity follows the provided `expires_at`.
- **success** (boolean) - Authentication success indicator.

#### Response Example
```json
{
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "session_key": "0x9876543210fedcba9876543210fedcba98765432",
  "jwt_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "success": true
}
```

### EIP-712 Typed Data Structure
```json
{
  "types": {
    "EIP712Domain": [
      { "name": "name", "type": "string" }
    ],
    "Policy": [
      { "name": "challenge", "type": "string" },
      { "name": "scope", "type": "string" },
      { "name": "wallet", "type": "address" },
      { "name": "session_key", "type": "address" },
      { "name": "expires_at", "type": "uint64" },
      { "name": "allowances", "type": "Allowance[]" }
    ],
    "Allowance": [
      { "name": "asset", "type": "string" },
      { "name": "amount", "type": "string" }
    ]
  },
  "primaryType": "Policy",
  "domain": {
    "name": "<application_name>"  // From auth_request
  },
  "message": {
    "challenge": "<challenge_message>",  // From auth_challenge
    "scope": "<scope>",                  // From auth_request
    "wallet": "<address>",               // From auth_request
    "session_key": "<session_key>",      // From auth_request
    "expires_at": "<expires_at>",        // From auth_request (13-digit Unix ms)
    "allowances": "<allowances>"         // From auth_request
  }
}
```

### Error Cases
- **Invalid signature**: EIP-712 signature doesn't match main wallet or is malformed. Recover by verifying the main wallet private key and EIP-712 structure.
- **Challenge expired**: Challenge older than 5 minutes. Recover by restarting the auth flow from `auth_request`.
- **Challenge already used**: Challenge has been verified already. Recover by generating a new session or using an existing one if still valid.
- **Invalid challenge**: Challenge not found in pending auths. Recover by ensuring `auth_request` succeeded first.
- **Challenge mismatch**: Challenge doesn't match pending auth. Recover by using the exact challenge from `auth_challenge`.
```

--------------------------------

### Get Session Keys

Source: https://docs.yellow.org/docs/protocol/off-chain/authentication

Retrieves the status of active sessions, including their remaining allowances and expiration details.

```APIDOC
## GET /websites/yellow_protocol/get_session_keys

### Description
Use `get_session_keys` to view active sessions and their remaining allowances. The response includes session details with current allowance usage and respects the `expires_at` provided during `auth_request`.

### Method
GET

### Endpoint
`/websites/yellow_protocol/get_session_keys`

### Parameters
#### Query Parameters
- **expires_at** (timestamp) - Optional - The expiration time for the session, as provided during `auth_request`.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "method": "get_session_keys",
  "params": {},
  "id": 1
}
```

### Response
#### Success Response (200)
- **sessions** (array) - An array of active session objects.
  - **sessionId** (string) - Unique identifier for the session.
  - **allowance** (number) - The total spending allowance for the session.
  - **used** (number) - The amount of allowance already used.
  - **remaining** (number) - The remaining allowance.
  - **expires_at** (timestamp) - The expiration timestamp of the session.

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "result": {
    "sessions": [
      {
        "sessionId": "sess_abc123",
        "allowance": 10000,
        "used": 500,
        "remaining": 9500,
        "expires_at": 1678886400
      }
    ]
  },
  "id": 1
}
```

#### Error Response (400)
- **res** (array) - Contains error details.
  - **requestId** (string) - The request ID.
  - **"error"** (string) - Literal string "error".
  - **errorObject** (object) - An object containing the error message.
    - **error** (string) - A descriptive error message (e.g., "session expired, please re-authenticate").
  - **timestamp** (number) - The timestamp of the error.
- **sig** (array) - The clearnode signature.
```

--------------------------------

### Method Implementation API

Source: https://docs.yellow.org/docs/protocol/implementation-checklist

Details on implementing various methods for channel management, transfers, app sessions, and queries.

```APIDOC
## Method Implementation API

### Description
Outlines the available methods for interacting with the Yellow Protocol, including channel management, transfers, app sessions, and various queries.

### Methods
- **Authentication**: `auth_request`, `auth_verify`
- **Channel Management**: `create_channel`, `close_channel`, `resize_channel`
- **Transfers**: `transfer`
- **App Sessions**: `create_app_session`, `submit_app_state`, `close_app_session`
- **Queries**: `get_config`, `get_assets`, `get_app_definition`, `get_channels`, `get_app_sessions`, `get_ledger_balances`, `get_ledger_entries`, `get_ledger_transactions`, `get_rpc_history`, `get_user_tag`, `get_session_keys`, `ping`
- **Server Notifications**: `bu` (Balance Update), `cu` (Channel Update), `tr` (Transfer), `asu` (App Session Update).
```

--------------------------------

### GET /ledger_balances

Source: https://docs.yellow.org/docs/protocol/off-chain/queries

Retrieves the ledger balances for an account, either a wallet or an app session. Returns all tracked assets.

```APIDOC
## GET /ledger_balances

### Description
Retrieves the ledger balances for an account. If no parameters are provided, returns the authenticated user's unified balance across all assets. Can also query balance within a specific app session by providing the app_session_id. Returns all tracked assets (including those that currently evaluate to zero).

### Method
GET

### Endpoint
/ledger_balances

### Parameters
#### Query Parameters
- **account_id** (string) - Optional - Account or app session identifier.  0x-prefixed hex string or wallet address.

### Request Example
```json
{
  "account_id": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
}
```

### App Session Balances
To query balance within a specific app session, provide the `app_session_id` as the `account_id`.
```

--------------------------------

### POST /auth/request - Initiate Session Key Authentication

Source: https://docs.yellow.org/docs/protocol/off-chain/authentication

Initiates the authentication process by registering a session key. This is the first step in the 3-step challenge-response flow for session key authentication. This is a public endpoint.

```APIDOC
## POST /auth/request

### Description
Initiates the authentication process by registering a session key. This endpoint is used as the first step in the 3-step challenge-response protocol to establish an authenticated session with Clearnode using a session key. The session key can be configured with specific permissions, spending limits, and expiration times.

**Note**: This is a public endpoint and does not require any signature. It is optional; you can choose to use your main wallet as a root signer for all requests instead.

### Method
POST

### Endpoint
`/auth/request`

### Parameters
#### Request Body
- **authParams** (object) - Required - Authentication parameters required to register a session key. The exact structure will depend on the specific Clearnode implementation but typically includes details for key generation and policy definition.
  - **Example**: `{"publicKey": "0x...", "permissions": {...}, "allowances": {...}, "expiration": "timestamp"}`
```

--------------------------------

### GET /channels

Source: https://docs.yellow.org/docs/protocol/off-chain/queries

Retrieves a list of channels, optionally filtering by participant or status. Supports pagination for large result sets.

```APIDOC
## GET /channels

### Description
Retrieves a list of channels, optionally filtering by participant or status. Supports pagination for large result sets.

### Method
GET

### Endpoint
/channels

### Parameters
#### Query Parameters
- **participant** (string) - Optional - Participant wallet address to query
- **status** (string) - Optional - Filter by status. Allowed values: "open", "closed", "challenged", "resizing"
- **offset** (number) - Optional - Pagination offset (default: 0)
- **limit** (number) - Optional - Number of channels to return (max 100, default: 10)
- **sort** (string) - Optional - Sort order by created_at (default: "desc")

### Response
#### Success Response (200)
- **channels** (array<Channel>) - List of channels. See Channel Structure below.

#### Response Example
```json
{
  "channels": [
    {
      "channel_id": "0xabcdef...",
      "participant": "0x742d35Cc...",
      "status": "open",
      "token": "0x2791Bca1...",
      "wallet": "0x742d35Cc...",
      "amount": "100.0",
      "chain_id": 137,
      "adjudicator": "0xAdjudicator...",
      "challenge": 3600,
      "nonce": 1699123456789,
      "version": 5,
      "created_at": "2023-05-01T12:00:00Z",
      "updated_at": "2023-05-01T14:30:00Z"
    }
  ]
}
```

#### Channel Structure
- **channel_id** (string) - Unique channel identifier
- **participant** (string) - User's wallet address
- **status** (string) - Channel status
- **token** (string) - Asset contract address
- **wallet** (string) - Participant's wallet address
- **amount** (string) - Total channel capacity (human-readable)
- **chain_id** (uint32) - Blockchain network identifier
- **adjudicator** (string) - Dispute resolution contract address
- **challenge** (uint64) - Dispute timeout period (seconds)
- **nonce** (uint64) - Unique nonce ensuring channel uniqueness
- **version** (uint64) - Current state version
- **created_at** (string) - Channel creation timestamp (ISO 8601)
- **updated_at** (string) - Last modification timestamp (ISO 8601)
```

--------------------------------

### App Definition and Allocation

Source: https://docs.yellow.org/docs/protocol/off-chain/app-sessions

This section details the structure for defining an app session, including protocol version, participants, weights, quorum, and optional challenge and nonce. It also describes the format for specifying asset allocations per participant.

```APIDOC
## POST /websites/yellow_protocol/app_sessions

### Description
Creates a new app session with specified definition and allocation parameters.

### Method
POST

### Endpoint
/websites/yellow_protocol/app_sessions

### Parameters
#### Request Body
- **protocol** (string) - Required - Protocol version for this app session. Use 'NitroRPC/0.4' for new sessions.
- **participants** (address[]) - Required - Array of all participant wallet addresses. Order is important.
- **weights** (int64[]) - Required - Voting power for each participant. Length must match participants array.
- **quorum** (uint64) - Required - Minimum total weight required to approve state updates.
- **challenge** (uint64) - Optional - Challenge period in seconds for disputes. Defaults to 86400 (24 hours).
- **nonce** (uint64) - Required - Unique identifier, typically a timestamp.
- **allocations** (object[]) - Required - Array of allocation objects, each specifying participant, asset, and amount.
  - **participant** (address) - Required - Participant wallet address (must be in `definition.participants`).
  - **asset** (string) - Required - Asset identifier (e.g., "usdc").
  - **amount** (string) - Required - Amount in human-readable format (e.g., "100.0").

### Request Example
```json
{
  "protocol": "NitroRPC/0.4",
  "participants": ["0x742d35Cc...", "0x8B3192f2...", "0x456789ab..."],
  "weights": [50, 50, 100],
  "quorum": 100,
  "challenge": 3600,
  "nonce": 1699123456789,
  "allocations": [
    {"participant": "0x742d35Cc...", "asset": "usdc", "amount": "100.0"},
    {"participant": "0x8B3192f2...", "asset": "usdc", "amount": "100.0"},
    {"participant": "0x456789ab...", "asset": "usdc", "amount": "0.0"}
  ]
}
```

### Response
#### Success Response (200)
- **app_session_id** (string) - Unique identifier for the created app session.
- **status** (string) - App session status (`"open"` or `"closed"`).
- **version** (number) - Current state version, starts at 1.

#### Response Example
```json
{
  "app_session_id": "0x9876543210fedcba9876543210fedcba9876543210fedcba9876543210fedcba",
  "status": "open",
  "version": 1
}
```
```
Tokens:
Raw