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

# Fan API

## Fetch tickets

> Fetch future tickets for the authenticated user.

```json
{"openapi":"3.1.0","info":{"title":"Fan API","version":"1.0.0"},"servers":[{"url":"https://api.kydlabs.com/fans"}],"security":[{"OIDC":["fan:tickets:read"]}],"components":{"securitySchemes":{"OIDC":{"type":"oauth2","description":"KYD OIDC authorization code flow. Use PKCE S256 and send the resulting access token as a bearer token.","flows":{"authorizationCode":{"authorizationUrl":"https://auth.kydlabs.com/oauth2/authorize","tokenUrl":"https://auth.kydlabs.com/oauth2/token","scopes":{"openid":"OpenID Connect identity scope.","profile":"Basic user profile claims.","fan:tickets:read":"Read fan ticket inventory.","fan:listings:write":"Create and cancel listing authorizations.","fan:claims:write":"Claim tickets using signed TIX transfer transactions."}}}}},"schemas":{"FetchTicketsResponse":{"type":"object","additionalProperties":false,"properties":{"user_id":{"type":"string"},"tickets":{"type":"array","items":{"$ref":"#/components/schemas/Ticket"}}},"required":["user_id","tickets"]},"Ticket":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string"},"kyd_event_id":{"type":"string"},"tix_event_id":{"type":"string"},"tix_ticket_id":{"type":"string"},"ticket_type_id":{"type":"string"},"event_name":{"type":"string"},"ticket_type_name":{"type":"string"},"purchase_date":{"type":"string"}},"required":["id","kyd_event_id","tix_event_id","tix_ticket_id","ticket_type_id","event_name","ticket_type_name","purchase_date"]},"ErrorResponse":{"type":"object","additionalProperties":false,"properties":{"message":{"type":"string"}},"required":["message"]}},"responses":{"Unauthorized":{"description":"Missing, expired, or invalid access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"The access token does not include the required Fan API permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/tickets":{"get":{"operationId":"fetchTickets","summary":"Fetch tickets","description":"Fetch future tickets for the authenticated user.","parameters":[{"name":"event_id","in":"query","required":false,"schema":{"type":"string"},"description":"Filter tickets by event. This can be a KYD Labs event ID or an onchain TIX ID."}],"responses":{"200":{"description":"Tickets for the authenticated user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FetchTicketsResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}}}}
```

## Create authorization

> Accepts authorization requests for creating or canceling a ticket listing and returns a signed authorization payload.

```json
{"openapi":"3.1.0","info":{"title":"Fan API","version":"1.0.0"},"servers":[{"url":"https://api.kydlabs.com/fans"}],"security":[{"OIDC":["fan:listings:write"]}],"components":{"securitySchemes":{"OIDC":{"type":"oauth2","description":"KYD OIDC authorization code flow. Use PKCE S256 and send the resulting access token as a bearer token.","flows":{"authorizationCode":{"authorizationUrl":"https://auth.kydlabs.com/oauth2/authorize","tokenUrl":"https://auth.kydlabs.com/oauth2/token","scopes":{"openid":"OpenID Connect identity scope.","profile":"Basic user profile claims.","fan:tickets:read":"Read fan ticket inventory.","fan:listings:write":"Create and cancel listing authorizations.","fan:claims:write":"Claim tickets using signed TIX transfer transactions."}}}}},"schemas":{"CreateAuthorizationRequest":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["list","cancel"],"description":"Listing action to authorize."},"transactions":{"type":"array","minItems":1,"maxItems":4,"description":"Hex- or base64-encoded serialized transactions. Every transaction must contain the listing action specified by `type`.","items":{"type":"string"}}},"required":["type","transactions"]},"CreateAuthorizationResponse":{"type":"object","additionalProperties":false,"properties":{"transactions":{"type":"array","description":"Signed hex-encoded serialized transactions in request order.","items":{"type":"string"}}},"required":["transactions"]},"ErrorResponse":{"type":"object","additionalProperties":false,"properties":{"message":{"type":"string"}},"required":["message"]}},"responses":{"Unauthorized":{"description":"Missing, expired, or invalid access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"The access token does not include the required Fan API permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"The requested ticket or listing was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/authorizations":{"post":{"operationId":"createAuthorization","summary":"Create authorization","description":"Accepts authorization requests for creating or canceling a ticket listing and returns a signed authorization payload.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAuthorizationRequest"}}}},"responses":{"200":{"description":"Signed listing authorization payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAuthorizationResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## Execute ticket claims

> Validates signed TIX transfer transactions and claims the referenced tickets for the authenticated user.

```json
{"openapi":"3.1.0","info":{"title":"Fan API","version":"1.0.0"},"servers":[{"url":"https://api.kydlabs.com/fans"}],"security":[{"OIDC":["fan:claims:write"]}],"components":{"securitySchemes":{"OIDC":{"type":"oauth2","description":"KYD OIDC authorization code flow. Use PKCE S256 and send the resulting access token as a bearer token.","flows":{"authorizationCode":{"authorizationUrl":"https://auth.kydlabs.com/oauth2/authorize","tokenUrl":"https://auth.kydlabs.com/oauth2/token","scopes":{"openid":"OpenID Connect identity scope.","profile":"Basic user profile claims.","fan:tickets:read":"Read fan ticket inventory.","fan:listings:write":"Create and cancel listing authorizations.","fan:claims:write":"Claim tickets using signed TIX transfer transactions."}}}}},"schemas":{"ExecuteClaimRequest":{"type":"object","additionalProperties":false,"properties":{"tickets":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"object","additionalProperties":false,"properties":{"tx":{"type":"string","pattern":"^(?:[0-9a-fA-F]{2})+$","description":"Hex-encoded signed Solana transaction containing one transfer_permit_v1 instruction."}},"required":["tx"]}}},"required":["tickets"]},"ExecuteClaimResponse":{"type":"object","additionalProperties":false,"properties":{"tickets":{"type":"array","items":{"$ref":"#/components/schemas/ExecutedClaim"}}},"required":["tickets"]},"ExecutedClaim":{"type":"object","additionalProperties":false,"properties":{"tix_event_id":{"type":"string"},"tix_permit_id":{"type":"string"},"ticket_id":{"type":"string"},"signer_wallet":{"type":"string"},"destination_wallet":{"type":"string"},"transfer_id":{"type":"string"}},"required":["tix_event_id","tix_permit_id","ticket_id","signer_wallet","destination_wallet","transfer_id"]},"ErrorResponse":{"type":"object","additionalProperties":false,"properties":{"message":{"type":"string"}},"required":["message"]}},"responses":{"BadRequest":{"description":"The request body or a claim transaction is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Missing, expired, or invalid access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"The access token does not include the required Fan API permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"The requested ticket or listing was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/claims/execute":{"post":{"operationId":"executeClaim","summary":"Execute ticket claims","description":"Validates signed TIX transfer transactions and claims the referenced tickets for the authenticated user.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExecuteClaimRequest"}}}},"responses":{"200":{"description":"Tickets claimed for the authenticated user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExecuteClaimResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```