> For the complete documentation index, see [llms.txt](https://docs.creditcoop.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.creditcoop.xyz/developer-api-docs/credit-facilities.md).

# Credit Facilities

Credit facility management

## List credit facilities

> List enabled Credit Facilities. Authentication is required. Users see credit facilities for public orgs plus private orgs they have access to.

```json
{"openapi":"3.0.3","info":{"title":"Credit Coop API","version":"3.0.0"},"tags":[{"name":"Credit Facilities","description":"Credit facility management"}],"servers":[{"url":"https://api.creditcoop.xyz"}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]},{"OAuth2":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key in the format: cc_xxx_yyy (for customer API routes)"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Clerk authentication token (session JWT or Clerk OAuth access token) used by Credit Coop"},"OAuth2":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://clerk.creditcoop.xyz/oauth/authorize","tokenUrl":"https://clerk.creditcoop.xyz/oauth/token","scopes":{"openid":"OpenID Connect","email":"User email","profile":"User profile"}}},"description":"Credit Coop OAuth"}},"schemas":{"CreditFacility":{"type":"object","required":["id","address","networkId","protocolVersion","label","organizationId"],"properties":{"id":{"type":"string","format":"uuid","description":"Credit facility unique identifier"},"address":{"type":"string","description":"SecuredLine contract address"},"networkId":{"type":"string","description":"CAIP-2 network identifier"},"protocolVersion":{"type":"string","nullable":true,"description":"Credit Coop protocol/contract generation (e.g. \"v1\", \"v2\"). Null when not classified."},"label":{"type":"string","nullable":true,"description":"Display label for the credit facility. Always present; null if not configured."},"organizationId":{"type":"string","format":"uuid","nullable":true,"description":"Borrower organization ID"},"organization":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/Organization"}],"description":"Organization details with links. Only included when expand includes \"organization\"."},"relatedAddresses":{"type":"object","nullable":true,"description":"On-chain related addresses. Only included when expand includes \"related-addresses\".","properties":{"spigot":{"type":"string","nullable":true,"description":"Spigot contract address. Captures and routes borrower revenue to debt repayment."},"borrower":{"type":"string","nullable":true,"description":"Address authorized to borrow, repay, and close credit lines"},"admin":{"type":"string","nullable":true,"description":"Credit facility administrator address"},"spigotOperator":{"type":"string","nullable":true,"description":"Address authorized to execute revenue claims on the Spigot"},"escrow":{"type":"string","nullable":true,"description":"Escrow contract address. Holds collateral posted by the borrower and enforces the minimum collateral ratio."}}},"fees":{"type":"object","nullable":true,"description":"Fee configuration for the Credit Facility. Only included when expand includes \"fees\".","required":["originationFee","swapFee","servicingFee"],"properties":{"originationFee":{"type":"string","description":"Origination fee (basis points)"},"swapFee":{"type":"string","description":"Swap fee (basis points)"},"servicingFee":{"type":"string","description":"Servicing fee (basis points)"}}},"counts":{"type":"object","nullable":true,"description":"Active credit lines and open proposals counts. Only included when expand includes \"counts\".","required":["activeCreditLines","openProposals"],"properties":{"activeCreditLines":{"type":"integer","description":"Number of active credit lines"},"openProposals":{"type":"integer","description":"Number of open mutual consent proposals"}}},"status":{"type":"object","nullable":true,"description":"On-chain contract status. Only included when expand includes \"status\".","required":["code","label"],"properties":{"code":{"type":"integer","description":"Numeric status code (0: UNINITIALIZED, 1: ACTIVE, 2: LIQUIDATABLE, 3: REPAID, 4: INSOLVENT, 5: ABORTED)"},"label":{"type":"string","enum":["UNINITIALIZED","ACTIVE","LIQUIDATABLE","REPAID","INSOLVENT","ABORTED","UNKNOWN"],"description":"Human-readable status label. UNKNOWN is returned when the on-chain status code is outside the known range (e.g., a new status added by a future contract version)."}}},"collateral":{"type":"object","nullable":true,"description":"On-chain collateral state from the Escrow contract. Only included when expand includes \"collateral\". Null when the facility has no escrow, RPC is unavailable, or the facility predates the Escrow architecture.","required":["maxLtvBps","totalOutstandingDebt","collateralValue","ltvBps","targetLtvBps","collateralTokens"],"properties":{"maxLtvBps":{"type":"string","nullable":true,"description":"Maximum loan-to-value ratio allowed for this facility, in basis points (10000 = 100%). Computed server-side as 10000² / minimumCollateralRatio (integer floor). Null when the facility does not enforce a collateral requirement."},"totalOutstandingDebt":{"type":"string","nullable":true,"description":"Total outstanding debt in USD as a formatted decimal string with trailing zeros trimmed (e.g. \"1234.56\"). The debt token's decimals are read from the first active credit position and applied server-side. \"0\" when there are no active positions. Null when the facility does not enforce a collateral requirement."},"collateralValue":{"type":"string","nullable":true,"description":"Collateral value in USD as a formatted decimal string with trailing zeros trimmed (e.g. \"2000\" or \"1999.99\"). Formatted server-side. Null when the facility does not enforce a collateral requirement."},"ltvBps":{"type":"string","nullable":true,"description":"Current loan-to-value ratio in basis points: (totalOutstandingDebt × 10000) / collateralValue, computed server-side from raw on-chain values (decimals normalized before division). \"0\" when there is no outstanding debt. \"999999999\" (sentinel) when debt is positive but on-chain collateral value is 0 — the facility is effectively infinitely undercollateralized. Null when the facility does not enforce a collateral requirement, or when debt decimals could not be resolved."},"targetLtvBps":{"type":"string","nullable":true,"description":"Target LTV in basis points. Defines the minimum collateral value required to back the facility's credit limit (min collateral ≈ creditLimit × 10000 / targetLtvBps). Null when no target is configured for this facility."},"collateralTokens":{"type":"array","description":"Every token ever enabled as collateral on the Escrow, with its current on-chain amount and USD value. May be empty if EnableCollateral events have not been ingested for this Escrow.","items":{"type":"object","required":["address","amount","decimals","usdValue"],"properties":{"address":{"type":"string","description":"Collateral token address (ERC-20)."},"amount":{"type":"string","nullable":true,"description":"Current on-chain collateral amount (raw uint256; divide by `decimals` to get human-readable value). Null if the on-chain `getCollateralData` read failed."},"decimals":{"type":"integer","nullable":true,"description":"Decimals of the collateral token itself (for rendering `amount`). Null if ERC-20 metadata could not be fetched."},"usdValue":{"type":"string","nullable":true,"description":"USD value of the current collateral amount as a human-readable decimal string (e.g. \"1234.56\"), up to 6 decimal places with trailing zeros trimmed. Null if amount, price, or decimals is unavailable."}}}}}}}},"Organization":{"type":"object","required":["id","name","slug"],"properties":{"id":{"type":"string","format":"uuid","description":"Organization unique identifier"},"name":{"type":"string","maxLength":255,"description":"Organization display name"},"slug":{"type":"string","maxLength":100,"description":"URL-friendly identifier"},"header":{"type":"string","nullable":true,"description":"Short tagline or headline for the organization profile"},"description":{"type":"string","nullable":true,"description":"Brief summary of the organization"},"overview":{"type":"string","nullable":true,"description":"Long-form organization description (may contain Markdown)"},"links":{"type":"array","description":"Organization links and image assets. Labels starting with \"#\" are image assets (e.g. \"#logo\", \"#header\"); all others are external links (e.g. \"Twitter\", \"Website\").","items":{"type":"object","required":["id","label","url"],"properties":{"id":{"type":"string","format":"uuid","description":"Link unique identifier"},"label":{"type":"string","description":"Link type. \"#logo\" and \"#header\" denote image assets; other values (e.g. \"Twitter\", \"Website\") denote external links."},"linkText":{"type":"string","nullable":true,"description":"Display text for external links (e.g. \"@raincards\", \"rain.xyz\")"},"iconUrl":{"type":"string","nullable":true,"description":"Icon image URL for external links"},"url":{"type":"string","description":"Target URL (image URL for asset links, destination URL for external links)"}}}}}},"Pagination":{"type":"object","required":["total","limit","offset"],"properties":{"total":{"type":"integer","description":"Total number of records matching the query"},"limit":{"type":"integer","description":"Maximum number of records returned per page"},"offset":{"type":"integer","description":"Number of records skipped from the start"}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"},"statusCode":{"type":"integer"}}}}},"paths":{"/v3/credit-facilities":{"get":{"operationId":"listCreditFacilities","summary":"List credit facilities","tags":["Credit Facilities"],"description":"List enabled Credit Facilities. Authentication is required. Users see credit facilities for public orgs plus private orgs they have access to.","parameters":[{"schema":{"type":"string","maxLength":36,"format":"uuid"},"in":"query","name":"organizationId","required":false,"description":"Filter by borrower organization ID. Example: 550e8400-e29b-41d4-a716-446655440000"},{"schema":{"type":"string","maxLength":100},"in":"query","name":"address","required":false,"description":"Filter by credit facility address. Case-insensitive when networkId is omitted or is an EVM chain (eip155:*), case-sensitive otherwise."},{"schema":{"type":"string","maxLength":50},"in":"query","name":"networkId","required":false,"description":"Filter by network ID (CAIP-2 blockchain ID), e.g., `eip155:1` (Ethereum), `eip155:137` (Polygon), `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp` (Solana)"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"in":"query","name":"limit","required":false},{"schema":{"type":"integer","minimum":0,"default":0},"in":"query","name":"offset","required":false},{"schema":{"type":"array","style":"form","explode":false,"items":{"type":"string","enum":["related-addresses","fees","organization","counts","status","collateral"]}},"in":"query","name":"expand","required":false,"description":"Comma-separated list of fields to expand. Valid values: \"related-addresses\" (fetches on-chain addresses: spigot, borrower, admin, spigotOperator, escrow), \"fees\" (fetches fee configuration: originationFee, swapFee, servicingFee), \"organization\" (includes full organization object with links), \"counts\" (fetches activeCreditLines and openProposals), \"status\" (fetches on-chain contract status), \"collateral\" (fetches on-chain collateral state: maxLtvBps, collateralValue, totalOutstandingDebt, ltvBps, collateralTokens[])."}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["creditFacilities","pagination"],"properties":{"creditFacilities":{"type":"array","items":{"$ref":"#/components/schemas/CreditFacility"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Get credit facility by ID

> Get a single Credit Facility by ID. Authentication is required.

```json
{"openapi":"3.0.3","info":{"title":"Credit Coop API","version":"3.0.0"},"tags":[{"name":"Credit Facilities","description":"Credit facility management"}],"servers":[{"url":"https://api.creditcoop.xyz"}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]},{"OAuth2":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key in the format: cc_xxx_yyy (for customer API routes)"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Clerk authentication token (session JWT or Clerk OAuth access token) used by Credit Coop"},"OAuth2":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://clerk.creditcoop.xyz/oauth/authorize","tokenUrl":"https://clerk.creditcoop.xyz/oauth/token","scopes":{"openid":"OpenID Connect","email":"User email","profile":"User profile"}}},"description":"Credit Coop OAuth"}},"schemas":{"CreditFacility":{"type":"object","required":["id","address","networkId","protocolVersion","label","organizationId"],"properties":{"id":{"type":"string","format":"uuid","description":"Credit facility unique identifier"},"address":{"type":"string","description":"SecuredLine contract address"},"networkId":{"type":"string","description":"CAIP-2 network identifier"},"protocolVersion":{"type":"string","nullable":true,"description":"Credit Coop protocol/contract generation (e.g. \"v1\", \"v2\"). Null when not classified."},"label":{"type":"string","nullable":true,"description":"Display label for the credit facility. Always present; null if not configured."},"organizationId":{"type":"string","format":"uuid","nullable":true,"description":"Borrower organization ID"},"organization":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/Organization"}],"description":"Organization details with links. Only included when expand includes \"organization\"."},"relatedAddresses":{"type":"object","nullable":true,"description":"On-chain related addresses. Only included when expand includes \"related-addresses\".","properties":{"spigot":{"type":"string","nullable":true,"description":"Spigot contract address. Captures and routes borrower revenue to debt repayment."},"borrower":{"type":"string","nullable":true,"description":"Address authorized to borrow, repay, and close credit lines"},"admin":{"type":"string","nullable":true,"description":"Credit facility administrator address"},"spigotOperator":{"type":"string","nullable":true,"description":"Address authorized to execute revenue claims on the Spigot"},"escrow":{"type":"string","nullable":true,"description":"Escrow contract address. Holds collateral posted by the borrower and enforces the minimum collateral ratio."}}},"fees":{"type":"object","nullable":true,"description":"Fee configuration for the Credit Facility. Only included when expand includes \"fees\".","required":["originationFee","swapFee","servicingFee"],"properties":{"originationFee":{"type":"string","description":"Origination fee (basis points)"},"swapFee":{"type":"string","description":"Swap fee (basis points)"},"servicingFee":{"type":"string","description":"Servicing fee (basis points)"}}},"counts":{"type":"object","nullable":true,"description":"Active credit lines and open proposals counts. Only included when expand includes \"counts\".","required":["activeCreditLines","openProposals"],"properties":{"activeCreditLines":{"type":"integer","description":"Number of active credit lines"},"openProposals":{"type":"integer","description":"Number of open mutual consent proposals"}}},"status":{"type":"object","nullable":true,"description":"On-chain contract status. Only included when expand includes \"status\".","required":["code","label"],"properties":{"code":{"type":"integer","description":"Numeric status code (0: UNINITIALIZED, 1: ACTIVE, 2: LIQUIDATABLE, 3: REPAID, 4: INSOLVENT, 5: ABORTED)"},"label":{"type":"string","enum":["UNINITIALIZED","ACTIVE","LIQUIDATABLE","REPAID","INSOLVENT","ABORTED","UNKNOWN"],"description":"Human-readable status label. UNKNOWN is returned when the on-chain status code is outside the known range (e.g., a new status added by a future contract version)."}}},"collateral":{"type":"object","nullable":true,"description":"On-chain collateral state from the Escrow contract. Only included when expand includes \"collateral\". Null when the facility has no escrow, RPC is unavailable, or the facility predates the Escrow architecture.","required":["maxLtvBps","totalOutstandingDebt","collateralValue","ltvBps","targetLtvBps","collateralTokens"],"properties":{"maxLtvBps":{"type":"string","nullable":true,"description":"Maximum loan-to-value ratio allowed for this facility, in basis points (10000 = 100%). Computed server-side as 10000² / minimumCollateralRatio (integer floor). Null when the facility does not enforce a collateral requirement."},"totalOutstandingDebt":{"type":"string","nullable":true,"description":"Total outstanding debt in USD as a formatted decimal string with trailing zeros trimmed (e.g. \"1234.56\"). The debt token's decimals are read from the first active credit position and applied server-side. \"0\" when there are no active positions. Null when the facility does not enforce a collateral requirement."},"collateralValue":{"type":"string","nullable":true,"description":"Collateral value in USD as a formatted decimal string with trailing zeros trimmed (e.g. \"2000\" or \"1999.99\"). Formatted server-side. Null when the facility does not enforce a collateral requirement."},"ltvBps":{"type":"string","nullable":true,"description":"Current loan-to-value ratio in basis points: (totalOutstandingDebt × 10000) / collateralValue, computed server-side from raw on-chain values (decimals normalized before division). \"0\" when there is no outstanding debt. \"999999999\" (sentinel) when debt is positive but on-chain collateral value is 0 — the facility is effectively infinitely undercollateralized. Null when the facility does not enforce a collateral requirement, or when debt decimals could not be resolved."},"targetLtvBps":{"type":"string","nullable":true,"description":"Target LTV in basis points. Defines the minimum collateral value required to back the facility's credit limit (min collateral ≈ creditLimit × 10000 / targetLtvBps). Null when no target is configured for this facility."},"collateralTokens":{"type":"array","description":"Every token ever enabled as collateral on the Escrow, with its current on-chain amount and USD value. May be empty if EnableCollateral events have not been ingested for this Escrow.","items":{"type":"object","required":["address","amount","decimals","usdValue"],"properties":{"address":{"type":"string","description":"Collateral token address (ERC-20)."},"amount":{"type":"string","nullable":true,"description":"Current on-chain collateral amount (raw uint256; divide by `decimals` to get human-readable value). Null if the on-chain `getCollateralData` read failed."},"decimals":{"type":"integer","nullable":true,"description":"Decimals of the collateral token itself (for rendering `amount`). Null if ERC-20 metadata could not be fetched."},"usdValue":{"type":"string","nullable":true,"description":"USD value of the current collateral amount as a human-readable decimal string (e.g. \"1234.56\"), up to 6 decimal places with trailing zeros trimmed. Null if amount, price, or decimals is unavailable."}}}}}}}},"Organization":{"type":"object","required":["id","name","slug"],"properties":{"id":{"type":"string","format":"uuid","description":"Organization unique identifier"},"name":{"type":"string","maxLength":255,"description":"Organization display name"},"slug":{"type":"string","maxLength":100,"description":"URL-friendly identifier"},"header":{"type":"string","nullable":true,"description":"Short tagline or headline for the organization profile"},"description":{"type":"string","nullable":true,"description":"Brief summary of the organization"},"overview":{"type":"string","nullable":true,"description":"Long-form organization description (may contain Markdown)"},"links":{"type":"array","description":"Organization links and image assets. Labels starting with \"#\" are image assets (e.g. \"#logo\", \"#header\"); all others are external links (e.g. \"Twitter\", \"Website\").","items":{"type":"object","required":["id","label","url"],"properties":{"id":{"type":"string","format":"uuid","description":"Link unique identifier"},"label":{"type":"string","description":"Link type. \"#logo\" and \"#header\" denote image assets; other values (e.g. \"Twitter\", \"Website\") denote external links."},"linkText":{"type":"string","nullable":true,"description":"Display text for external links (e.g. \"@raincards\", \"rain.xyz\")"},"iconUrl":{"type":"string","nullable":true,"description":"Icon image URL for external links"},"url":{"type":"string","description":"Target URL (image URL for asset links, destination URL for external links)"}}}}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"},"statusCode":{"type":"integer"}}}}},"paths":{"/v3/credit-facilities/{id}":{"get":{"operationId":"getCreditFacility","summary":"Get credit facility by ID","tags":["Credit Facilities"],"description":"Get a single Credit Facility by ID. Authentication is required.","parameters":[{"schema":{"type":"array","style":"form","explode":false,"items":{"type":"string","enum":["related-addresses","fees","organization","counts","status","collateral"]}},"in":"query","name":"expand","required":false,"description":"Comma-separated list of fields to expand. Valid values: \"related-addresses\" (fetches on-chain addresses: spigot, borrower, admin, spigotOperator, escrow), \"fees\" (fetches fee configuration: originationFee, swapFee, servicingFee), \"organization\" (includes full organization object with links), \"counts\" (fetches activeCreditLines and openProposals), \"status\" (fetches on-chain contract status), \"collateral\" (fetches on-chain collateral state: maxLtvBps, collateralValue, totalOutstandingDebt, ltvBps, collateralTokens[])."},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Credit Facility ID. Example: 550e8400-e29b-41d4-a716-446655440000"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditFacility"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Get credit facility credit lines

> Get credit lines for a Credit Facility. Authentication is required.

```json
{"openapi":"3.0.3","info":{"title":"Credit Coop API","version":"3.0.0"},"tags":[{"name":"Credit Facilities","description":"Credit facility management"}],"servers":[{"url":"https://api.creditcoop.xyz"}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]},{"OAuth2":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key in the format: cc_xxx_yyy (for customer API routes)"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Clerk authentication token (session JWT or Clerk OAuth access token) used by Credit Coop"},"OAuth2":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://clerk.creditcoop.xyz/oauth/authorize","tokenUrl":"https://clerk.creditcoop.xyz/oauth/token","scopes":{"openid":"OpenID Connect","email":"User email","profile":"User profile"}}},"description":"Credit Coop OAuth"}},"schemas":{"CreditLine":{"type":"object","required":["lineTokenId"],"properties":{"lineTokenId":{"type":"string","description":"Credit line token ID"},"deposit":{"type":"string","nullable":true,"description":"Deposit amount (raw uint256 — divide by 10^decimals to get human-readable value)"},"creditLimit":{"type":"string","nullable":true,"description":"Credit limit (raw uint256 — divide by 10^decimals to get human-readable value). For open lines: equals current deposit. For closed lines: deposit from the most recent AddCredit or IncreaseCredit event."},"principal":{"type":"string","nullable":true,"description":"Principal amount borrowed (raw uint256 — divide by 10^decimals to get human-readable value)"},"interestBalance":{"type":"string","nullable":true,"description":"Total interest balance (raw uint256 — divide by 10^decimals to get human-readable value). Open lines: interestAccrued + interestRepaid. Closed lines: interestRepaid."},"interestAccrued":{"type":"string","nullable":true,"description":"Interest accrued (raw uint256 — divide by 10^decimals to get human-readable value)"},"interestRepaid":{"type":"string","nullable":true,"description":"Interest repaid (raw uint256 — divide by 10^decimals to get human-readable value)"},"token":{"type":"string","nullable":true,"description":"Token address for this credit line"},"decimals":{"type":"integer","nullable":true,"description":"Token decimals"},"isOpen":{"type":"boolean","nullable":true,"description":"Whether the credit line is open"},"isRestricted":{"type":"boolean","nullable":true,"description":"Whether the credit line is restricted"},"earlyWithdrawalFee":{"type":"string","nullable":true,"description":"Early withdrawal fee in basis points"},"deadline":{"type":"string","format":"date-time","nullable":true,"description":"Credit line deadline"},"drawRate":{"type":"string","nullable":true,"description":"Draw rate in basis points (interest rate on borrowed principal)"},"facilityRate":{"type":"string","nullable":true,"description":"Facility rate in basis points (interest rate on unused deposit)"},"apyPct":{"type":"number","nullable":true,"description":"Computed APY as a percentage (e.g. 5.0 = 5.0%). Weighted average of drawRate on principal and facilityRate on unused deposit."},"createdTxHash":{"type":"string","nullable":true,"description":"Transaction hash of the AddCredit event that created this line"},"createdBlockNumber":{"type":"integer","nullable":true,"description":"Block number when this credit line was created"},"createdAt":{"type":"string","format":"date-time","nullable":true,"description":"Timestamp when this credit line was created"},"fees":{"type":"object","nullable":true,"description":"Only included when expand=fees is specified. Null if fetching failed.","required":["originationFees"],"properties":{"originationFees":{"type":"string","description":"Total origination fees paid for this credit line (raw uint256 — divide by 10^decimals to get human-readable value)"}}},"error":{"type":"string","nullable":true,"description":"Error message if fetching this credit line failed. Other fields will be null."}}},"FacilityCreditLineRelatedAddresses":{"type":"object","required":["lender"],"properties":{"lender":{"type":"string","description":"Lender address (owner of the credit line NFT)"},"vault":{"type":"string","nullable":true,"description":"Lending vault address associated with the lender"},"vaultCurator":{"type":"string","nullable":true,"description":"Vault curator address for the lender"}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"},"statusCode":{"type":"integer"}}}}},"paths":{"/v3/credit-facilities/{id}/credit-lines":{"get":{"operationId":"getCreditFacilityCreditLines","summary":"Get credit facility credit lines","tags":["Credit Facilities"],"description":"Get credit lines for a Credit Facility. Authentication is required.","parameters":[{"schema":{"type":"array","style":"form","explode":false,"items":{"type":"string","enum":["related-addresses","fees"]}},"in":"query","name":"expand","required":false,"description":"Comma-separated list of fields to expand. Valid values: \"related-addresses\" (includes relatedAddresses object with lender, vault, vaultCurator on each credit line), \"fees\" (includes fees object with originationFees on each credit line)."},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Credit Facility ID. Example: 550e8400-e29b-41d4-a716-446655440000"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["facilityId","facilityAddress","networkId","activeCount","totalCount","creditLines","totals"],"properties":{"facilityId":{"type":"string","description":"Credit Facility UUID"},"facilityAddress":{"type":"string","description":"Credit facility contract address"},"networkId":{"type":"string","description":"CAIP-2 network identifier (e.g. eip155:8453)"},"activeCount":{"type":"integer","description":"Number of active credit lines"},"totalCount":{"type":"integer","description":"Total number of credit lines"},"fees":{"type":"object","nullable":true,"description":"Fee configuration for the credit facility. Null if fees could not be fetched.","required":["originationFee","swapFee","servicingFee"],"properties":{"originationFee":{"type":"string","description":"Origination fee (basis points)"},"swapFee":{"type":"string","description":"Swap fee (basis points)"},"servicingFee":{"type":"string","description":"Servicing fee (basis points)"}}},"creditLines":{"type":"array","description":"Credit lines ordered by repayment queue position (first item is repaid first)","items":{"allOf":[{"$ref":"#/components/schemas/CreditLine"},{"type":"object","properties":{"relatedAddresses":{"nullable":true,"description":"Only included when expand=related-addresses is specified. Contains lender, vault, and vaultCurator addresses. Null if fetching failed.","allOf":[{"$ref":"#/components/schemas/FacilityCreditLineRelatedAddresses"}]}}}]}},"totals":{"type":"object","required":["depositUsd","principalUsd","interestAccruedUsd","interestRepaidUsd","interestBalanceUsd","creditLimitUsd"],"description":"Aggregated totals in USD. depositUsd/principalUsd/interestAccruedUsd/interestRepaidUsd/interestBalanceUsd cover all non-errored credit lines (open + closed) — closed lines can still hold non-zero balances on-chain. creditLimitUsd covers OPEN lines only because closed-line creditLimit is the historical authorised credit at close, not an active obligation. apyPct is the USD-deposit-weighted average across open lines. Any USD field is null if a contributing line lacks a USD price.","properties":{"depositUsd":{"type":"string","nullable":true,"description":"Sum across all non-errored lines (open + closed) of deposit converted to USD."},"principalUsd":{"type":"string","nullable":true,"description":"Sum across all non-errored lines (open + closed) of outstanding principal converted to USD."},"interestAccruedUsd":{"type":"string","nullable":true,"description":"Sum across all non-errored lines (open + closed) of accrued interest converted to USD."},"interestRepaidUsd":{"type":"string","nullable":true,"description":"Sum across all non-errored lines (open + closed) of repaid interest converted to USD."},"interestBalanceUsd":{"type":"string","nullable":true,"description":"Sum across all non-errored lines (open + closed) of interest balance converted to USD. Open lines: accrued + repaid. Closed lines: repaid only."},"creditLimitUsd":{"type":"string","nullable":true,"description":"Sum across OPEN credit lines only of creditLimit converted to USD. Closed lines are excluded because their creditLimit is the historical authorised credit at close, not an active obligation."},"apyPct":{"type":"number","nullable":true,"description":"USD-deposit-weighted average APY across open lines (e.g. 5.0 = 5.0%). For multi-token facilities the weighting is in USD so each line contributes proportionally to its USD exposure. Falls back to raw-deposit-weighted APY (with drawRate fallback) when no open line has a priced non-zero deposit. Null if no APY can be derived."}}}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Get credit facility proposals

> Get mutual consent proposals for a Credit Facility. Authentication is required.

```json
{"openapi":"3.0.3","info":{"title":"Credit Coop API","version":"3.0.0"},"tags":[{"name":"Credit Facilities","description":"Credit facility management"}],"servers":[{"url":"https://api.creditcoop.xyz"}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]},{"OAuth2":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key in the format: cc_xxx_yyy (for customer API routes)"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Clerk authentication token (session JWT or Clerk OAuth access token) used by Credit Coop"},"OAuth2":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://clerk.creditcoop.xyz/oauth/authorize","tokenUrl":"https://clerk.creditcoop.xyz/oauth/token","scopes":{"openid":"OpenID Connect","email":"User email","profile":"User profile"}}},"description":"Credit Coop OAuth"}},"schemas":{"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"},"statusCode":{"type":"integer"}}}}},"paths":{"/v3/credit-facilities/{id}/proposals":{"get":{"operationId":"getCreditFacilityProposals","summary":"Get credit facility proposals","tags":["Credit Facilities"],"description":"Get mutual consent proposals for a Credit Facility. Authentication is required.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Credit Facility ID. Example: 550e8400-e29b-41d4-a716-446655440000"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["facilityId","facilityAddress","networkId","open","closed","revokedAllEvents"],"properties":{"facilityId":{"type":"string","description":"Credit Facility UUID"},"facilityAddress":{"type":"string","description":"Credit facility contract address"},"networkId":{"type":"string","description":"CAIP-2 network identifier (e.g. eip155:8453)"},"open":{"type":"array","description":"Proposals that are still open (pending acceptance)","items":{"type":"object","required":["proposalId","taker","nonce","proposalType","status","registeredAt","registeredTxHash","registeredBlockNumber"],"properties":{"proposalId":{"type":"string","description":"Unique proposal identifier (bytes32)"},"taker":{"type":"string","description":"Address that needs to accept the proposal"},"nonce":{"type":"string","description":"Nonce at time of registration"},"msgData":{"type":"string","nullable":true,"description":"Raw hex-encoded function call data from the proposal"},"proposalType":{"type":"string","enum":["new_credit","refinance","set_fees","unknown"],"description":"Type of proposal: new_credit for new credit lines, refinance for modifications, set_fees for fee changes, unknown if ABI missing or function is not recognized"},"parameters":{"oneOf":[{"title":"CreditProposalParameters","type":"object","description":"Credit proposal parameters (new_credit or refinance)","required":["lender","amount","drawRate","facilityRate","deadline"],"properties":{"lender":{"type":"string","description":"Lender address"},"vaultCurator":{"type":"string","nullable":true,"description":"Vault curator (manager) address for the lender"},"vault":{"type":"string","nullable":true,"description":"Lending vault address for the lender (CreditStrategy)"},"token":{"type":"string","nullable":true,"description":"Token address"},"amount":{"type":"string","description":"Credit amount (raw uint256 — divide by the token's decimals to get human-readable value)"},"drawRate":{"type":"string","description":"Draw rate in basis points"},"facilityRate":{"type":"string","description":"Facility rate in basis points"},"deadline":{"type":"string","format":"date-time","description":"Expiration"},"isRestricted":{"type":"boolean","description":"Whether credit is restricted (new_credit only)"},"earlyWithdrawalFee":{"type":"string","description":"Early withdrawal fee in basis points (new_credit only)"},"lineTokenId":{"type":"string","description":"Existing credit line token ID (refinance only)"},"desiredNonce":{"type":"string","description":"Nonce the proposer required at acceptance, decoded from msgData (new_credit and refinance only)"}}},{"title":"SetFeesProposalParameters","type":"object","description":"Fee change parameters (set_fees)","required":["originationFee","swapFee","servicingFee"],"properties":{"originationFee":{"type":"string","description":"Origination fee in basis points"},"swapFee":{"type":"string","description":"Swap fee in basis points"},"servicingFee":{"type":"string","description":"Servicing fee in basis points"}}},{"type":"null"}],"description":"Decoded proposal terms. Shape depends on proposalType: credit parameters for new_credit/refinance, fee parameters for set_fees, null for unknown."},"status":{"type":"string","enum":["pending"],"description":"Proposal status (always pending for open proposals)"},"registeredAt":{"type":"string","format":"date-time"},"registeredTxHash":{"type":"string"},"registeredBlockNumber":{"type":"integer"}}}},"closed":{"type":"array","description":"Proposals that have been closed (accepted, revoked, or revoked_all)","items":{"type":"object","required":["proposalId","taker","nonce","proposalType","status","registeredAt","registeredTxHash","registeredBlockNumber","closedAt","closedTxHash","closedBlockNumber"],"properties":{"proposalId":{"type":"string","description":"Unique proposal identifier (bytes32)"},"taker":{"type":"string","description":"Address that needed to accept the proposal"},"nonce":{"type":"string","description":"Nonce at time of registration"},"msgData":{"type":"string","nullable":true,"description":"Raw hex-encoded function call data from the proposal"},"proposalType":{"type":"string","enum":["new_credit","refinance","set_fees","unknown"],"description":"Type of proposal: new_credit for new credit lines, refinance for modifications, set_fees for fee changes, unknown if ABI missing or function is not recognized"},"parameters":{"oneOf":[{"title":"CreditProposalParameters","type":"object","description":"Credit proposal parameters (new_credit or refinance)","required":["lender","amount","drawRate","facilityRate","deadline"],"properties":{"lender":{"type":"string","description":"Lender address"},"vaultCurator":{"type":"string","nullable":true,"description":"Vault curator (manager) address for the lender"},"vault":{"type":"string","nullable":true,"description":"Lending vault address for the lender (CreditStrategy)"},"token":{"type":"string","nullable":true,"description":"Token address"},"amount":{"type":"string","description":"Credit amount (raw uint256 — divide by the token's decimals to get human-readable value)"},"drawRate":{"type":"string","description":"Draw rate in basis points"},"facilityRate":{"type":"string","description":"Facility rate in basis points"},"deadline":{"type":"string","format":"date-time","description":"Expiration"},"isRestricted":{"type":"boolean","description":"Whether credit is restricted (new_credit only)"},"earlyWithdrawalFee":{"type":"string","description":"Early withdrawal fee in basis points (new_credit only)"},"lineTokenId":{"type":"string","description":"Existing credit line token ID (refinance only)"},"desiredNonce":{"type":"string","description":"Nonce the proposer required at acceptance, decoded from msgData (new_credit and refinance only)"}}},{"title":"SetFeesProposalParameters","type":"object","description":"Fee change parameters (set_fees)","required":["originationFee","swapFee","servicingFee"],"properties":{"originationFee":{"type":"string","description":"Origination fee in basis points"},"swapFee":{"type":"string","description":"Swap fee in basis points"},"servicingFee":{"type":"string","description":"Servicing fee in basis points"}}},{"type":"null"}],"description":"Decoded proposal terms. Shape depends on proposalType: credit parameters for new_credit/refinance, fee parameters for set_fees, null for unknown."},"status":{"type":"string","enum":["accepted","revoked","revoked_all"],"description":"How the proposal was closed"},"registeredAt":{"type":"string","format":"date-time"},"registeredTxHash":{"type":"string"},"registeredBlockNumber":{"type":"integer"},"closedAt":{"type":"string","format":"date-time"},"closedTxHash":{"type":"string"},"closedBlockNumber":{"type":"integer"}}}},"revokedAllEvents":{"type":"array","description":"All RevokedAll events that cleared proposals","items":{"type":"object","required":["newNonce","timestamp","txHash","blockNumber"],"properties":{"newNonce":{"type":"string","description":"New nonce after revocation"},"timestamp":{"type":"string","format":"date-time"},"txHash":{"type":"string"},"blockNumber":{"type":"integer"}}}}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.creditcoop.xyz/developer-api-docs/credit-facilities.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.