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

# Royalty

> Royalty allows you to manage royalty payments and claims within Story.

## Royalty

### Methods

* pay\_royalty\_on\_behalf
* claimable\_revenue
* claim\_all\_revenue
* get\_royalty\_vault\_address
* transfer\_to\_vault

### pay\_royalty\_on\_behalf

Allows the function caller to pay royalties to a receiver IP asset on behalf of the payer IP Asset.

| Method                  |
| ----------------------- |
| `pay_royalty_on_behalf` |

Parameters:

* `receiver_ip_id`: The ipId that receives the royalties.
* `payer_ip_id`: The ID of the IP asset that pays the royalties.
* `token`: The token to use to pay the royalties.
* `amount`: The amount to pay.
* `tx_options`: \[Optional] The transaction options dictionary.

<CodeGroup>
  ```python Python theme={null}
  from web3 import Web3

  # In this case, lets say there is a root IPA 'A' and a derivative IPA 'B'.
  # Someone wants to pay 'B' for whatever reason (they bought it, they want to tip it, etc).
  # Since the payer is not an IP Asset (rather an external user), the `payer_ip_id` can
  # be a zero address. And the receiver is, well, the receiver's ipId which is B.
  #
  # It's important to note that both 'B' and its parent 'A' will be able
  # to claim revenue from this based on the negotiated license terms
  pay_royalty = story_client.Royalty.pay_royalty_on_behalf(
      receiver_ip_id="0x0b825D9E5FA196e6B563C0a446e8D9885057f9B1",  # B's ipId
      payer_ip_id="0x0000000000000000000000000000000000000000",  # zero address
      token="0x1514000000000000000000000000000000000000",  # $WIP
      amount=Web3.to_wei(2, 'ether'),  # 2 $WIP
      tx_options={"wait_for_transaction": True}
  )
  print(f"Paid royalty at transaction hash {pay_royalty['tx_hash']}")

  # In this case, lets say there is a root IPA 'A' and a derivative IPA 'B'.
  # 'B' earns revenue off-chain, but must pay 'A' based on their negotiated license terms.
  # So 'B' pays 'A' what they are due
  pay_royalty = story_client.Royalty.pay_royalty_on_behalf(
      receiver_ip_id="0x6B86B39F03558A8a4E9252d73F2bDeBfBedf5b68",  # A's ipId
      payer_ip_id="0x0b825D9E5FA196e6B563C0a446e8D9885057f9B1",  # B's ipId
      token="0x1514000000000000000000000000000000000000",  # $WIP
      amount=Web3.to_wei(2, 'ether'),  # 2 $WIP
      tx_options={"wait_for_transaction": True}
  )
  print(f"Paid royalty at transaction hash {pay_royalty['tx_hash']}")
  ```

  ```python Request Parameters theme={null}
  receiver_ip_id: str  # The ipId that receives the royalties
  payer_ip_id: str  # The ID of the IP asset that pays the royalties
  token: str  # The token to use to pay the royalties
  amount: int  # The amount to pay
  tx_options: dict = None  # Optional: Transaction options
  ```

  ```python Response theme={null}
  {
    "tx_hash": str,  # The transaction hash
  }
  ```
</CodeGroup>

### claimable\_revenue

Get total amount of revenue token claimable by a royalty token holder.

| Method              |
| ------------------- |
| `claimable_revenue` |

Parameters:

* `royalty_vault_ip_id`: The id of the royalty vault.
* `claimer`: The address of the royalty token holder.
* `token`: The revenue token to claim.

<CodeGroup>
  ```python Python theme={null}
  claimable = story_client.Royalty.claimable_revenue(
      royalty_vault_ip_id="0x089d75C9b7E441dA3115AF93FF9A855BDdbfe384",
      claimer="0x089d75C9b7E441dA3115AF93FF9A855BDdbfe384",
      token="0x1514000000000000000000000000000000000000"  # $WIP
  )
  print(f"Claimable revenue: {claimable}")
  ```

  ```python Request Parameters theme={null}
  royalty_vault_ip_id: str  # The id of the royalty vault
  claimer: str  # The address of the royalty token holder
  token: str  # The revenue token to claim
  ```

  ```python Response theme={null}
  int  # The amount of revenue token claimable
  ```
</CodeGroup>

### claim\_all\_revenue

Claims all revenue from child IP Assets and/or from your own IP Royalty Vault.

| Method              |
| ------------------- |
| `claim_all_revenue` |

Parameters:

* `ancestor_ip_id`: The address of the ancestor IP from which the revenue is being claimed.
* `claimer`: The address of the claimer of the currency (revenue) tokens. This is normally the ipId of the ancestor IP if the IP has all royalty tokens. Otherwise, this would be the address that is holding the ancestor IP royalty tokens.
* `child_ip_ids`: The addresses of the child IPs from which royalties are derived.
* `royalty_policies`: The addresses of the royalty policies, where royalty\_policies\[i] governs the royalty flow for child\_ip\_ids\[i].
* `currency_tokens`: The addresses of the currency tokens in which royalties will be claimed.
* `claim_options`: \[Optional]
  * `claim_options['auto_transfer_all_claimed_tokens_from_ip']`: \[Optional] When enabled, all claimed tokens on the claimer are transferred to the wallet address if the wallet owns the IP. If the wallet is the claimer or if the claimer is not an IP owned by the wallet, then the tokens will not be transferred. Set to False to disable auto transferring claimed tokens from the claimer. **Default: True**

<CodeGroup>
  ```python Python theme={null}
  claim_revenue = story_client.Royalty.claim_all_revenue(
      # IP Asset 1's (parent) ipId
      ancestor_ip_id="0x089d75C9b7E441dA3115AF93FF9A855BDdbfe384",
      # whoever owns the royalty tokens associated with IP Royalty Vault 1
      # (most likely the associated ipId, which is IP Asset 1's ipId)
      claimer="0x089d75C9b7E441dA3115AF93FF9A855BDdbfe384",
      currency_tokens=["0x1514000000000000000000000000000000000000"],  # $WIP
      # IP Asset 2's (child) ipId
      child_ip_ids=["0xDa03c4B278AD44f5a669e9b73580F91AeDE0E3B2"],
      # testnet address of RoyaltyPolicyLAP
      royalty_policies=["0xBe54FB168b3c982b7AaE60dB6CF75Bd8447b390E"],
      claim_options={
        'auto_transfer_all_claimed_tokens_from_ip': True
      }
  )

  print(f"Claimed revenue: {claim_revenue['claimed_tokens']}")
  ```

  ```python Request Parameters theme={null}
  ancestor_ip_id: str  # The address of the ancestor IP
  claimer: str  # The address of the claimer of the currency tokens
  child_ip_ids: list  # The addresses of the child IPs
  royalty_policies: list  # The addresses of the royalty policies
  currency_tokens: list  # The addresses of the currency tokens
  claim_options: dict = None  # Optional: Claim options
  tx_options: dict = None  # Optional: Transaction options
  ```

  ```python Response theme={null}
  {
    "tx_hashes": list,  # The transaction hashes
    "receipt": dict,  # The transaction receipt
    "claimed_tokens": list  # List of claimed tokens with token address and amount
  }
  ```
</CodeGroup>

### get\_royalty\_vault\_address

Get the royalty vault proxy address of given `ip_id`.

| Method                      |
| --------------------------- |
| `get_royalty_vault_address` |

Parameters:

* `ip_id`: the `ipId` associated with the royalty vault.

<CodeGroup>
  ```python Python theme={null}
  vault_address = story_client.Royalty.get_royalty_vault_address("0x089d75C9b7E441dA3115AF93FF9A855BDdbfe384")
  print(f"Royalty vault address: {vault_address}")
  ```

  ```python Request Parameters theme={null}
  ip_id: str  # The ipId associated with the royalty vault
  ```

  ```python Response theme={null}
  str  # The royalty vault proxy address
  ```
</CodeGroup>

### transfer\_to\_vault

Transfers to vault an amount of revenue tokens claimable via a royalty policy.

| Method              |
| ------------------- |
| `transfer_to_vault` |

Parameters:

* `ip_id`: The ID of the IP asset that pays the royalties.
* `ancestor_ip_id`: The ID of the ancestor IP asset.
* `token`: The token address to transfer.
* `royalty_policy`: \[Optional] The royalty policy to use ("LAP" or "LRP"). **Default: "LAP"**
* `tx_options`: \[Optional] The transaction options dictionary.

<CodeGroup>
  ```python Python theme={null}
  transfer_result = story_client.Royalty.transfer_to_vault(
      ip_id="0x0b825D9E5FA196e6B563C0a446e8D9885057f9B1",
      ancestor_ip_id="0x6B86B39F03558A8a4E9252d73F2bDeBfBedf5b68",
      royalty_policy="LAP",
      token="0x1514000000000000000000000000000000000000",  # $WIP
  )
  print(f"Transferred to vault at transaction hash {transfer_result['tx_hash']}")
  ```

  ```python Request Parameters theme={null}
  ip_id: str  # The ID of the IP asset that pays the royalties
  ancestor_ip_id: str  # The ID of the ancestor IP asset
  token: str  # The token address to transfer
  royalty_policy: str = "LAP"  # The royalty policy to use ("LAP" or "LRP")
  tx_options: dict = None  # Optional: Transaction options
  ```

  ```python Response theme={null}
  {
    "tx_hash": str,  # The transaction hash
    "receipt": dict  # The transaction receipt, only available if wait_for_transaction is set to true
  }
  ```
</CodeGroup>