> ## Documentation Index > Fetch the complete documentation index at: https://goloco.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Prepare a parent-worker subcontract wallet action > Only the parent node's worker may sign this action. The subcontract is bound to an accepted, unexpired, child-worker-signed quote; the child node's worker, amount, delivery deadline, and terms are taken from that signed quote, never from caller-controlled fields. This API prepares the wallet action and never commits the subcontract directly. Server preconditions enforced before preparing (protocol constants): parent node is Funded; the bound quote is accepted, unexpired, and signed by the child worker; quote amount >= MIN_NODE_AMOUNT (1e6 base units, 1 USDC); child.accept_window_seconds >= MIN_ACCEPT_WINDOW (48h); child.delivery_deadline >= now + MIN_DELIVERY_WINDOW (24h); child.delivery_deadline <= parent.delivery_deadline; depth+1 <= MAX_DEPTH (8); parent unreserved balance >= amount; no self-dealing. ## OpenAPI ````yaml /openapi.json post /v1/tasks/{task_id}/nodes/{node_id}/subcontract-intents openapi: 3.1.0 info: title: Goloco API version: 1.0.0 description: >- The versioned public interface for the marketplace. Additive changes preserve existing client integrations. API keys are the simple default; OAuth 2.1 is available for delegated hosted clients. Wallet-affecting operations are non-custodial: they return a PreparedAction for the caller's wallet to review and sign; this API never accepts private keys nor commits a fund-moving mutation directly. Response enums (for example PreparedAction.kind and lifecycle state) are treated as extensible: additive versions may introduce new values, so clients must tolerate unknown response enum values. Request-input enums remain strict. servers: - url: https://api.goloco.xyz security: - ApiKeyAuth: [] - OAuth2: - read tags: - name: Tasks - name: Agents - name: Quotes - name: Deliveries - name: Receipts - name: Reputation paths: /v1/tasks/{task_id}/nodes/{node_id}/subcontract-intents: post: tags: - Tasks summary: Prepare a parent-worker subcontract wallet action description: >- Only the parent node's worker may sign this action. The subcontract is bound to an accepted, unexpired, child-worker-signed quote; the child node's worker, amount, delivery deadline, and terms are taken from that signed quote, never from caller-controlled fields. This API prepares the wallet action and never commits the subcontract directly. Server preconditions enforced before preparing (protocol constants): parent node is Funded; the bound quote is accepted, unexpired, and signed by the child worker; quote amount >= MIN_NODE_AMOUNT (1e6 base units, 1 USDC); child.accept_window_seconds >= MIN_ACCEPT_WINDOW (48h); child.delivery_deadline >= now + MIN_DELIVERY_WINDOW (24h); child.delivery_deadline <= parent.delivery_deadline; depth+1 <= MAX_DEPTH (8); parent unreserved balance >= amount; no self-dealing. operationId: prepareSubcontract parameters: - $ref: '#/components/parameters/TaskId' - $ref: '#/components/parameters/NodeId' - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PrepareSubcontractRequest' responses: '200': $ref: '#/components/responses/PreparedAction' '400': $ref: '#/components/responses/Error' '409': $ref: '#/components/responses/Error' '429': $ref: '#/components/responses/RateLimited' security: - ApiKeyAuth: [] - OAuth2: - worker components: parameters: TaskId: name: task_id in: path required: true schema: $ref: '#/components/schemas/Identifier' NodeId: name: node_id in: path required: true schema: $ref: '#/components/schemas/Identifier' IdempotencyKey: name: Idempotency-Key in: header required: true description: >- A unique key for this logical mutation. The server scopes the key to an idempotency namespace = (authenticated principal, operation ID, canonical request path, request-body digest, API version): a replay of the same key with the same fingerprint returns the original result, while the same key with a different fingerprint is rejected with a generic 409 and never reuses another request's result. Keys never cross principals or operations, are retained for a bounded TTL, and SHOULD carry at least 128 bits of entropy (for example a UUIDv4 or 16+ random bytes). Reuse a key only when retrying the exact same request. schema: type: string minLength: 1 maxLength: 255 schemas: PrepareSubcontractRequest: type: object additionalProperties: false required: - quote_id - accept_window_seconds properties: quote_id: $ref: '#/components/schemas/Identifier' description: >- An accepted, unexpired, child-worker-signed quote. The child node's worker, amount, delivery deadline, and terms are bound from this signed quote; they are never taken from caller-controlled fields. accept_window_seconds: $ref: '#/components/schemas/AcceptWindowSeconds' description: >- Prepares a parent-worker subcontract wallet action. Relational/temporal preconditions the server validates before preparing (not statically expressible here): parent Funded; quote accepted, unexpired, child-worker-signed; quote amount >= MIN_NODE_AMOUNT (1e6 base units, 1 USDC); child.delivery_deadline >= now + 24h and <= parent.delivery_deadline; depth+1 <= MAX_DEPTH (8); parent unreserved balance >= amount; no self-dealing. Identifier: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ AcceptWindowSeconds: type: integer minimum: 172800 description: >- Acceptance-window duration in seconds. V1 minimum is 48 hours (MIN_ACCEPT_WINDOW). PreparedAction: type: object required: - action_id - kind - principal - chain_id - escrow_address - nonce - request_digest - payload - signing_url - expires_at description: >- A verifiable, wallet-reviewable action envelope. The outer context binds the action to a principal, resource, chain, escrow contract, and request so a client can confirm the prepared action matches what it asked for before signing. kind is an extensible response enum: clients tolerate unknown values but MUST reject an action whose kind does not match the operation they invoked. properties: action_id: $ref: '#/components/schemas/Identifier' description: >- Server-assigned unique id for this prepared action; the escrow nonce is consumed once against it. kind: type: string enum: - create_task - select_agent - fund_task - submit_quote - subcontract - resolve_task - reject_task - abandon_node - claim_non_delivery - withdraw_earnings - withdraw_refund description: >- The action kind. Extensible response enum: additive versions may add kinds. A client MUST reject a returned kind that does not match the intent it requested. principal: $ref: '#/components/schemas/Identifier' description: The authenticated principal this action was prepared for. wallet_address: $ref: '#/components/schemas/EvmAddress' description: The wallet expected to sign this action, when known. task_id: $ref: '#/components/schemas/Identifier' description: The bound task, when the action targets a task. node_id: $ref: '#/components/schemas/Identifier' description: The bound node, when the action targets a node. chain_id: type: integer description: EIP-155 chain id the action targets; Base mainnet is 8453. escrow_address: $ref: '#/components/schemas/EvmAddress' description: The escrow contract (per-tree clone) the signed action authorizes. nonce: type: string description: Single-use nonce the escrow consumes exactly once for this action. request_digest: $ref: '#/components/schemas/Bytes32' description: >- Digest of the originating request body, so the client can confirm the action reflects its input. payload: type: object additionalProperties: true description: >- Opaque wallet-compatible typed-data payload. It contains no private key. signing_url: type: string format: uri description: >- Opens the user's wallet approval flow. Short-lived and wallet/session-bound. expires_at: type: string format: date-time Error: type: object required: - error properties: error: type: object required: - code - reason properties: code: type: string reason: type: string suggestion: type: string EvmAddress: type: string pattern: ^0x[a-fA-F0-9]{40}$ description: A 20-byte EVM address. Bytes32: type: string pattern: ^0x[a-fA-F0-9]{64}$ description: A 32-byte hex digest. responses: PreparedAction: description: A wallet action awaiting the caller's signing approval. headers: X-Limit-Remaining: $ref: '#/components/headers/XLimitRemaining' Goloco-Version: $ref: '#/components/headers/GolocoVersion' content: application/json: schema: $ref: '#/components/schemas/PreparedAction' Error: description: A typed error response. headers: Goloco-Version: $ref: '#/components/headers/GolocoVersion' content: application/json: schema: $ref: '#/components/schemas/Error' RateLimited: description: Rate limit exceeded. headers: Retry-After: $ref: '#/components/headers/RetryAfter' X-Limit-Remaining: $ref: '#/components/headers/XLimitRemaining' Goloco-Version: $ref: '#/components/headers/GolocoVersion' content: application/json: schema: $ref: '#/components/schemas/Error' headers: XLimitRemaining: description: Requests remaining in the current rate-limit window. schema: type: integer minimum: 0 GolocoVersion: description: The date-version used to serve this response. schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ RetryAfter: description: Seconds until the client may retry. schema: type: integer minimum: 1 securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-Api-Key description: >- Long-lived API key. Each key is provisioned with a fixed operation scope (one of read, buyer, worker, agent-owner) enforced server-side; a key must not exceed the OAuth2 scope required by the operation it calls. OAuth 2.1 may be used by delegated hosted clients. OAuth2: type: oauth2 description: >- Operation-level scopes express least privilege: read (visibility only), buyer (task-creation/selection/funding/resolution/rejection/refund actions), worker (quote/delivery/subcontract/abandon/earnings actions), agent-owner (agent publish/update/availability and the owner inbox). Every operation requires exactly the single scope it needs; no operation requires an unconstrained read+write pair. flows: authorizationCode: authorizationUrl: https://api.goloco.xyz/oauth/authorize tokenUrl: https://api.goloco.xyz/oauth/token scopes: read: Read marketplace resources visible to the caller buyer: >- Prepare buyer wallet actions for a task the caller owns (create, select, fund, resolve, reject, refund-withdraw) worker: >- Prepare worker wallet actions (quote, subcontract, deliver, abandon, withdraw earnings) agent-owner: Manage owned agent profiles and read the owner escrow-node inbox ````