> For the complete documentation index, see [llms.txt](https://docs.qiro.fi/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.qiro.fi/developer-section/openapi-spec/drawdowns/request-a-drawdown.md).

# Request a drawdown

Creates a durable drawdown resource and starts asynchronous eligibility validation. A `202` response does not mean the drawdown is approved or funded.

The high-level SDK continues by polling this resource, preparing the transaction, asking the partner's wallet to sign and broadcast, and verifying the confirmed request event. The SDK returns after borrower-request confirmation; admin approval and funding remain asynchronous.

The authenticated partner, facility ID, and idempotency key identify the operation. Repeating the same key with the same request returns the original resource. Reusing the key with a different request returns `IDEMPOTENCY_CONFLICT`.

The partner must not send a wallet, chain, contract, rate, fee, or limit. Qiro resolves those values from the approved facility.

```json
{"openapi":"3.1.0","info":{"title":"Qiro Partner Instant Settlement API","version":"1.0.0-draft"},"tags":[{"name":"Drawdowns","description":"Request, prepare, and track a drawdown against an approved facility."}],"servers":[{"url":"/","description":"Qiro API host supplied to the partner during onboarding."}],"security":[{"oauth2":["drawdowns:write"]}],"components":{"securitySchemes":{"oauth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"facilities:read":"Read facilities owned by the authenticated partner.","drawdowns:read":"Read partner drawdown resources.","drawdowns:write":"Create and prepare partner drawdowns.","repayments:read":"Read dues quotes and repayment resources.","repayments:write":"Create and prepare repayments.","closures:read":"Read facility closure dues and closure resources.","closures:write":"Create and prepare facility closures."}}}}},"parameters":{"FacilityId":{"name":"facility_id","in":"path","required":true,"description":"Stable Qiro identifier for one approved LOC facility.","schema":{"type":"string","pattern":"^fac_[A-Za-z0-9]+$"}},"CorrelationId":{"name":"X-Correlation-ID","in":"header","required":true,"description":"End-to-end request identifier. When the body contains `correlation_id`, both values must match.","schema":{"type":"string","minLength":1,"maxLength":128}},"IdempotencyKey":{"name":"X-Idempotency-Key","in":"header","required":true,"description":"UUID protecting a money-sensitive operation from duplicate execution. Qiro SDK methods generate and reuse it automatically.","schema":{"type":"string","format":"uuid"}}},"schemas":{"CreateDrawdownRequest":{"type":"object","additionalProperties":false,"required":["client_id","client_name","amount","settlement_asset","use_case","business_transaction","requested_tenor_days","correlation_id"],"properties":{"client_id":{"type":"string","minLength":1,"maxLength":128},"client_name":{"type":"string","minLength":1,"maxLength":256,"description":"Descriptive only; Qiro's stored borrower name remains authoritative."},"amount":{"allOf":[{"$ref":"#/components/schemas/PositiveMoneyString"}],"description":"Positive display-unit amount using the configured token precision."},"settlement_asset":{"type":"string","enum":["USDC","USDT"]},"use_case":{"$ref":"#/components/schemas/DrawdownUseCase"},"business_transaction":{"$ref":"#/components/schemas/BusinessTransaction"},"requested_tenor_days":{"type":"integer","minimum":1},"correlation_id":{"type":"string","minLength":1,"maxLength":128}}},"PositiveMoneyString":{"type":"string","pattern":"^(?:0\\.(?:0*\\d*[1-9]\\d*)|[1-9]\\d*(?:\\.\\d+)?)$","description":"Positive decimal display-unit amount. JSON numbers are not accepted."},"DrawdownUseCase":{"type":"string","enum":["REMITTANCE_PREFUNDING","PAYOUT_BATCH_PREFUNDING","CORRIDOR_LIQUIDITY"]},"BusinessTransaction":{"type":"object","additionalProperties":false,"required":["type","industry_type","settle_transaction_id","destination_currency","destination_country"],"properties":{"type":{"type":"string","enum":["SINGLE_REMITTANCE","PAYOUT_BATCH","CORRIDOR_FUNDING","FX_TRADE","TREASURY_TRANSFER"]},"industry_type":{"type":"string","enum":["REMITTANCE_AND_MONEY_TRANSFER","CROSS_BORDER_PAYMENTS","B2B_PAYMENTS","SUPPLIER_PAYMENTS","PAYROLL","MARKETPLACE_PAYOUTS","MERCHANT_SETTLEMENT","E_COMMERCE","TRAVEL","EDUCATION","HEALTHCARE","FINANCIAL_SERVICES","PROFESSIONAL_SERVICES","LOGISTICS","OTHER"]},"settle_transaction_id":{"type":"string","minLength":1,"maxLength":128},"external_reference":{"type":"string","minLength":1,"maxLength":128},"source_currency":{"$ref":"#/components/schemas/CurrencyCode"},"source_country":{"$ref":"#/components/schemas/CountryCode"},"destination_currency":{"$ref":"#/components/schemas/CurrencyCode"},"destination_country":{"$ref":"#/components/schemas/CountryCode"}}},"CurrencyCode":{"type":"string","pattern":"^[A-Z]{3}$","description":"ISO 4217 currency code."},"CountryCode":{"type":"string","pattern":"^[A-Z]{2}$","description":"ISO 3166-1 alpha-2 country code."},"Drawdown":{"type":"object","additionalProperties":false,"required":["drawdown_id","facility_id","client","status","amount","amount_base_units","settlement_asset","use_case","business_transaction","designated_wallet","requested_tenor_days","duration_seconds","correlation_id","rejection","failure","blockchain_evidence","funded_drawdown_id","created_at","updated_at","resource_version"],"properties":{"drawdown_id":{"type":"string","pattern":"^drw_[A-Za-z0-9]+$"},"facility_id":{"type":"string","pattern":"^fac_[A-Za-z0-9]+$"},"client":{"$ref":"#/components/schemas/Client"},"status":{"$ref":"#/components/schemas/DrawdownStatus"},"amount":{"$ref":"#/components/schemas/MoneyString"},"amount_base_units":{"$ref":"#/components/schemas/UnsignedIntegerString"},"settlement_asset":{"type":"string","enum":["USDC","USDT"]},"use_case":{"$ref":"#/components/schemas/DrawdownUseCase"},"business_transaction":{"$ref":"#/components/schemas/BusinessTransaction"},"designated_wallet":{"$ref":"#/components/schemas/BoundWallet"},"requested_tenor_days":{"type":"integer","minimum":1},"duration_seconds":{"$ref":"#/components/schemas/UnsignedIntegerString"},"correlation_id":{"type":"string","minLength":1,"maxLength":128},"rejection":{"oneOf":[{"$ref":"#/components/schemas/WorkflowReason"},{"type":"null"}]},"failure":{"oneOf":[{"$ref":"#/components/schemas/WorkflowReason"},{"type":"null"}]},"blockchain_evidence":{"type":"array","items":{"$ref":"#/components/schemas/DrawdownChainEvidence"}},"funded_drawdown_id":{"oneOf":[{"$ref":"#/components/schemas/UnsignedIntegerString"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"resource_version":{"type":"integer","minimum":1}}},"Client":{"type":"object","additionalProperties":false,"required":["client_id","client_name","client_type"],"properties":{"client_id":{"type":"string","minLength":1},"client_name":{"type":"string","minLength":1},"client_type":{"type":"string","const":"REMITTANCE_COMPANY"}}},"DrawdownStatus":{"type":"string","description":"Current normalized partner workflow state.","enum":["VALIDATING","READY_FOR_SUBMISSION","SUBMITTING","AWAITING_APPROVAL","FUNDED","REPAID","REJECTED","FAILED"]},"MoneyString":{"type":"string","pattern":"^(0|[1-9]\\d*)(\\.\\d+)?$","description":"Decimal display-unit amount. JSON numbers are not accepted."},"UnsignedIntegerString":{"type":"string","pattern":"^(0|[1-9]\\d*)$"},"BoundWallet":{"type":"object","additionalProperties":false,"required":["wallet_id","wallet_version"],"properties":{"wallet_id":{"type":"string","pattern":"^wal_[A-Za-z0-9]+$"},"wallet_version":{"type":"integer","minimum":1}}},"WorkflowReason":{"type":"object","additionalProperties":false,"required":["code"],"properties":{"code":{"type":"string","minLength":1}}},"DrawdownChainEvidence":{"type":"object","additionalProperties":false,"required":["event_name","chain_id","contract_address","transaction_hash","log_index","block_number","block_hash","observed_at"],"properties":{"event_name":{"type":"string","enum":["DrawdownRequested","DrawdownApproved","DrawdownRejected"]},"chain_id":{"type":"integer","minimum":1},"contract_address":{"$ref":"#/components/schemas/EvmAddress"},"transaction_hash":{"$ref":"#/components/schemas/TransactionHash"},"log_index":{"type":"integer","minimum":0},"block_number":{"$ref":"#/components/schemas/UnsignedIntegerString"},"block_hash":{"$ref":"#/components/schemas/TransactionHash"},"observed_at":{"type":"string","format":"date-time"}}},"EvmAddress":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"TransactionHash":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$"},"ErrorResponse":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Safe human-readable explanation."},"request_id":{"type":"string"},"correlation_id":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":"object","additionalProperties":true},"issues":{"type":"array","items":{"type":"string"}}}}}}},"headers":{"CorrelationId":{"description":"Echo of the request correlation identifier.","schema":{"type":"string","minLength":1,"maxLength":128}}},"responses":{"BadRequest":{"description":"Invalid schema, field format, or correlation identifier.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"The bearer token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"The authenticated partner does not own the resource or lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"FacilityNotFound":{"description":"The facility was not found for the authenticated partner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ResourceConflict":{"description":"Idempotency, workflow state, or verified facility identity conflicts with the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"EligibilityRejected":{"description":"The request is valid but rejected by facility, policy, liquidity, or contract rules.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ServiceUnavailable":{"description":"Contract, RPC, subgraph, or reconciliation infrastructure is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/v1/facilities/{facility_id}/drawdowns":{"post":{"tags":["Drawdowns"],"operationId":"createDrawdown","summary":"Request a drawdown","description":"Creates a durable drawdown resource and starts asynchronous eligibility validation.\nA `202` response does not mean the drawdown is approved or funded.\n\nThe high-level SDK continues by polling this resource, preparing the transaction, asking\nthe partner's wallet to sign and broadcast, and verifying the confirmed request event. The SDK\nreturns after borrower-request confirmation; admin approval and funding remain asynchronous.\n\nThe authenticated partner, facility ID, and idempotency key identify the operation.\nRepeating the same key with the same request returns the original resource. Reusing\nthe key with a different request returns `IDEMPOTENCY_CONFLICT`.\n\nThe partner must not send a wallet, chain, contract, rate, fee, or limit. Qiro resolves\nthose values from the approved facility.\n","parameters":[{"$ref":"#/components/parameters/FacilityId"},{"$ref":"#/components/parameters/CorrelationId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDrawdownRequest"}}}},"responses":{"202":{"description":"Drawdown accepted for asynchronous validation.","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/CorrelationId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Drawdown"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/FacilityNotFound"},"409":{"$ref":"#/components/responses/ResourceConflict"},"422":{"$ref":"#/components/responses/EligibilityRejected"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}}}}
```
